UNIX-Type APIs (V5R2) 


Sockets APIs 


Table of Contents 


Sockets APIs 


e System functions 


o APIs 


m accept() (Wait for an incoming connection and tie that connection to the 
application) 

m accept_and_recv() (Wait for connection request and receive the first message that 
was sent) 


m bindQ (Set a local address for the socket) 

m close() (Close file descriptor) 

m connect() (Bind a destination to a socket or set a connection) 
m fcntl( (Perform file control command) 

m fstatQ (Get file information by descriptor) 

m getdomainname() (Retrieve domain name for the system) 

m gethostid( (Retrieve host ID for the system) 

m gethostname() (Retrieve host name for the system) 

m getpeername() (Retrieve destination address of a socket) 

m getsockname() (Retrieve local address of a socket) 


m getsockopt( (Allow an application to request information about a socket (timeout, 
retransmission, buffer space)) 


m givedescriptor() (Pass the access rights to a descriptor) 
m ioctl() (Perform file I/O control request) 
m listenQ (Prepare a socket for incoming connections) 


m QsoCreatelJOCompletionPort() (Create I/O Completion Port) 


m QsoDestroyIOCompletionPort() (Destroy I/O Completion Port) 


= QsoPostlOCompletion( (Post I/O Completion Request) 
m QsoStartAcceptQ (Start Asynchronous Accept Operation) 
m QsoStartRecv() (Start Asynchronous Receive Operation) 
m QsoStartSendQ (Start Asynchronous Send Operation) 

mg QsoWaitForlOCompletion( (Wait for I/O Operation) 

m RbindQ (Establish remote bind) 


m read() (Read from Descriptor) 

m readv( (Read from Descriptor Using Multiple Buffers) 

m recv() (Receive data using a socket descriptor). 

m recvfrom() (Receive data and remote address using a socket descriptor) 


m recvmsg() (Receive data and remote address using a socket descriptor and multiple 
buffers (scatter read)) 


m rexec() (Issue a command on a remote host) 

m rexec_r() (Issue a command on a remote host) 

m rexec_r_ts64() (Issue a command on a remote host) 

m rexec_tx64() (Issue a command on a remote host) 

m select() (Allow a single process to wait for connections on multiple sockets) 
m sendQ (Send data using a socket descriptor) 


m sendmsg() (Send data with a destination address using a socket descriptor and 
multiple buffers (gather write)) 


m sendtoQ (Send data with a destination address using a socket descriptor) 
m send_fileQ (Send a file over a socket connection) 

m send_file64Q (Send a file over a socket connection) 

m setdomainname() (Set domain name for the system) 

m sethostidQ (Set Host ID) is used to set a host ID. 

m sethostname() (Set host name for the system) 


m setsockopt() (Allow an application to set characteristics of a socket (timeout, 
retransmission, buffer space)) 


m shutdownQ (End Receiving and/or Sending of Data on Socket) 
m= socket() (Create a socket) is used to create an end point for communications. 
m socketpair() (Create a pair of sockets) 
m takedescriptor() (Receive the access rights to a descriptor) 
m@ write() (Write to Descriptor) 
@ writev( (Write to Descriptor Using Multiple Buffers) 
o Using XOPEN_SOURCE for UNIX 98 Compatibility 


e Network functions 


oO dn_compQ) (Compress an expanded domain name) 

o dn_comp_ts64() (Compress an expanded domain name) 
oO dn_expandQ (Expand a compressed domain name) 
O 


dn_find(Q (Search for a compressed domain name from a list of previously compressed 
domain names) 


o dn_find_ts640 (Search for a compressed domain name from a list of previously 
compressed domain names) 


o dn_skipname() (Skip over a compressed domain name) 


O 0 09 0 80 O80 0 0 


O 


O 


O 0 0 0 0 OO 0 


endhostent() (Close the nameserver database) 

endhostent_r(Q) (Close the nameserver database) 

endnetent() (Close the network database) 

endnetent_r() (Close the network database) 

endprotoent() (Close the protocol database) 

endprotoent_r() (Close the protocol database) 

endservent() (Close the service database) 

endservent_r() (Close the service database) 

®freeaddrinfo() (Free Address Information)* 

eai_strerror() (Retrieve Address Information Runtime Error Message)*& 
oetaddrinfo() (Get Address Information)*& 

gethostbyaddr() (Provide information about host given an Internet address) 
gethostbyaddr_r(Q) (Provide information about host given an Internet address) 


gethostbyname() (Provide information about host given a host name) 


gethostbyname_r() (Provide information about host given a host name) 


gethostentQ) (Get next host entry from the nameserver database) 

gethostent_r() (Get next host entry from the nameserver database) 

2getnameinfo() (Get Name Information for Socket Address)*& 

getnetbyaddr() (Get information from the network database about a given internet address) 


getnetbyaddr_r(Q (Get information from the network database about a given internet 
address) 


getnetbyname() (Get information from the network database about a given domain name) 
getnetbyname_r() (Get information from the network database about a given domain name) 
getnetent() (Get network entry from the network database) 

getnetent_r() (Get network entry from the network database) 

getprotobyname() (Get information regarding a protocol given the protocol name) 


getprotobyname_r() (Get information regarding a protocol given the protocol name) 


getprotobynumber() (Get information regarding a protocol given the protocol number) 


getprotobynumber_r() (Get information regarding a protocol given the protocol number) 


getprotoent() (Get next protocol entry in the protocol data base) 
getprotoent_r() (Get next protocol entry in the protocol data base) 
getservbyname() (Get port number for a given service name) 
getservbyname_r() (Get port number for a given service name) 
getservbyport() (Get service name given a port number) 
getservbyport_r() (Get service name given a port number) 
getservent() (Get next service entry from the service database) 


Oo 


Oo 


Oo 


getservent_r() (Get next service entry from the service database) 

hstrerror() (Retrieve resolver error message) 

htonlO (Convert a long (4 byte) integer from local host byte order to the network byte 
order) 


htons() (Convert a short (2 byte) integer from local host byte order to the network byte 
order) 

inet_addr(Q) (Translate the full address from dotted decimal format to a 32-bit Internet 
address) 


inet_Inaof() (Separate the local portion of an Internet address) 


oO inet_makeaddr() (Formulate an Internet address that combines a network address with the 


local address of a host) 
inet_netof() (Separate the network portion of an Internet address) 


O inet_networkQ (Translate the network portion of the address from dotted decimal format to 


O 0 0 09 09 O09 O09 O09 O89 8 0 


a 32-bit Internet address) 

inet_ntoa() (Translate from 32-bit Internet address to a dotted decimal format) 
inet_ntoa_rQ (Translate from 32-bit Internet address to a dotted decimal format) 
#?inet_ntop() (Convert IPv4 and IPv6 Addresses Between Binary and Text Form)*& 
#*inet_pton() (Convert IPv4 and IPv6 Addresses Between Text and Binary Form)*& 
ns_addr() (Translate a network services address from human readable format to a 12-byte 
hexadecimal address) 


ns_ntoa() (Translate a network services address from a 12-byte address to a human 
readable format) 


ns_ntoa_rQ) (Translate a network services address from a 12-byte address to a human 
readable format) 


ntohlQ (Convert a long (4 byte) integer from network byte order to the local host byte 
order) 


ntohs() (Convert a short (2 byte) integer from network byte order to the local host byte 
order) 


res_close() (Close a socket and reset the _res structure) 
res_findzonecut() (Find the enclosing zone and servers) 
res_hostaliasQ (Retrieve the host alias) 


res_init() (Initialize _res structure for domain name server) 


res_mkquery(Q) (Form a domain name query and place it in a buffer in memory) 
res_nclose() (Close socket and reset res structure) 

res_ninit() (Initialize res structure) 

res_nisourserver() (Check server address) 

res_nmkquery() (Place domain query in buffer) 

res_nmkupdate() (Construct an update packet) 

res_nquery() (Send domain query) 


res_nquerydomain() (Send 2-string domain query) 
res_nsearch() (Search for domain name) 
res_nsend() (Send buffered domain query or update) 


res_nsendsigned() (Send authenticated domain query or update) 


res_nupdate() (Build and send dynamic updates) 


res_query() (Form a domain name query and send it to the domain name server) 
res_search() (Search for a domain name from a list of domain names) 
res_sendQ (Send the query formed in res_mkquery to the domain name server) 
res_xlate() (Translate standard DNS packets between ASCII and EBCDIC) 
sethostent() (Open the nameserver database) 
sethostent_r() (Open the nameserver database) 
setnetent() (Open the network database) 
setnetent_r( (Open the network database) 
setprotoent() (Open the protocol database) 
setprotoent_r() (Open the protocol database) 
setservent() (Open the service database) 
setservent_r() (Open the service database) 

getlong() (Get long byte quantities from a byte stream) 

getshort() (Get short byte quantities from a byte stream) 


O oO. o8 OO © 8 oO OO OD CO O VM CO OO OD 0 © 2 0 


putlong() (Put long byte quantities into a byte stream) 
Oo _putshort() (Put short byte quantities into a byte stream) 
e Debugging IP over SNA Configurations 


Header Files for UNIX-Type Functions 
Errno Values for UNIX-Type Functions 


Sockets APIs 


The sockets APIs consist of functions, structures, and defined macros. The structures and defined macros 
are shipped as header files. 


An important part of interprocess communications is to locate and construct network addresses. Many of 
the socket network APIs are inherently not threadsafe. Threadsafe APIs have been added to mirror the 
function provided by the non-threadsafe APIs. All threadsafe APIs follow the UNIX convention of 
appending R to the API name denoting threadsafe. 


There are two categories of sockets functions: 


e@ system functions 


e network functions 


For additional information, see: 


e Sockets Programming 


e Debugging IP over SNA Configurations 
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Sockets System Functions 


The system functions supported by the sockets APIs are: 


accept() (Wait for an incoming connection and tie that connection to the application) is used to wait 
for connection requests. 


accept_and_recv() (Wait for connection request and receive the first message that was sent) is used 


to wait for an incoming connection request, receive the first message from the peer, and return the 
local and remote socket addresses associated with the connection. 


bindQ (Set a local address for the socket) is used to associate a local address with a socket. 

closeQ) (Close file descriptor) closes a descriptor, fildes. 

connect() (Bind a destination to a socket or set a connection) is used to establish a connection on a 
connection-oriented socket or establish the destination address on a connectionless socket. 

fcntlO (Perform file control command) performs various actions on open descriptors. 


fstatQ (Get file information by descriptor) gets status information about the file specified by the 


open file descriptor file_descriptor and stores the information in the area of memory indicated by 
the buf argument. 


getdomainname() (Retrieve domain name for the system) is used to retrieve the name of the domain 
from the system. 


gethostid(Q (Retrieve host ID for the system) is used to retrieve a host ID's 32-bit IP address. 


gethostname() (Retrieve host name for the system) is used to retrieve the name of the host from the 
system. 


getpeername() (Retrieve destination address of a socket) is used to retrieve the destination address 
to which the socket is connected. 

getsockname() (Retrieve local address of a socket) is used to retrieve the local address associated 
with the socket. 

getsockopt() (Allow an application to request information about a socket (timeout, retransmission, 
buffer space)) is used to retrieve information about socket options. 

givedescriptor() (Pass the access rights to a descriptor) is used to pass a descriptor from one OS/400 
job to another OS/400 job. 

ioctl) (Perform file I/O control request) performs control functions (requests) on a file descriptor. 
listenQ (Prepare a socket for incoming connections) is used to indicate a willingness to accept 
incoming connection requests. If a listen() is not done, incoming connections are silently discarded. 
QsoCreateIOCompletionPort() (Create I/O Completion Port) is used to create a common wait point 
for a completed overlapped I/O operation. 


QsoDestroy[OCompletionPortQ (Destroy I/O Completion Port) is used to destroy an I/O 
completion port. 


QsoPostlOCompletion() (Post I/O Completion Request) will post an Qso_OverlappedIO_t request 
on a specifed I/O completion port. 


QsoStartAccept() (Start Asynchronous Accept Operation) is used to wait asynchronously for 
connection requests. 


QsoStartRecvQ (Start Asynchronous Receive Operation) is used to initiate a asynchronous receive 
operation. 


QsoStartSendQ) (Start Asynchronous Send Operation) is used to initiate a asynchronous send 


operation. 


QsoWaitForlIOCompletionQ (Wait for I/O Operation) is used to wait for a completed overlapped 
I/O operation. 


RbindQ (Establish remote bind) used to request that a SOCKS server allow an inbound connection 
request across a firewall. 


readQ) (Read from Descriptor) reads nbyte bytes of input into the memory area indicated by buf. 
readv() (Read from Descriptor Using Multiple Buffers) is used to receive data from a file or socket 
descriptor. 

recv() (Receive data using a socket descriptor) is used to receive data through a socket. 

recvfrom() (Receive data and remote address using a socket descriptor) is used to receive data 
through a connected or unconnected socket. 


recvmsg() (Receive data and remote address using a socket descriptor and multiple buffers (scatter 
read)) is used to receive data or descriptors or both through a connected or unconnected socket. 


rexec() (Issue a command on a remote host) is used to open a connection to a remote host and send 
a user ID, password, and command to the remote host. 


rexec_r() (Issue a command on a remote host) is used to open a connection to a remote host and 
send a user ID, password, and command to the remote host. 


rexec_r_ts64() (Issue a command on a remote host) is used to open a connection to a remote host 
and send a user ID, password, and command to the remote host. 


rexec_tx64() (Issue a command on a remote host) is used to open a connection to a remote host and 
send a user ID, password, and command to the remote host. 


select() (Allow a single process to wait for connections on multiple sockets) is used to enable an 
application to multiplex I/O. 


send() (Send data using a socket descriptor) is used to send data through a connected socket. 


sendmsg() (Send data with a destination address using a socket descriptor and multiple buffers 


(gather write)) is used to send data or descriptors or both through a connected or unconnected 
socket. 


sendto(Q (Send data with a destination address using a socket descriptor) is used to send data 
through a connected or unconnected socket. 


send_file() (Send a file over a socket connection) is used to send the contents of an open file over 
an existing socket connection. 


send_file64(Q (Send a file over a socket connection) is used to send the contents of an open file over 
an existing socket connection. 


setdomainname() (Set domain name for the system) is used to set the name of the domain. 


sethostidQ (Set Host ID) is used to set a host ID. 


sethostname() (Set host name for the system) is used to set the name of the host for a system. 
setsockopt() (Allow an application to set characteristics of a socket (timeout, retransmission, buffer 
space)) is used to set socket options. 


shutdownQ (End Receiving and/or Sending of Data on Socket) is used to disable reading, writing, 
or reading and writing on a socket. 


socket() (Create a socket) is used to create an end point for communications. 


socketpair() (Create a pair of sockets) is used to create a pair of unnamed, connected sockets in the 
AF_UNIX or AF_UNIX_CCSID address_family. 


e takedescriptor() (Receive the access rights to a descriptor) is used to obtain a descriptor in one 
OS/400 job which was passed from another OS/400 job by a givedescriptor(). 


@ writeQ (Write to Descriptor) writes nbyte bytes from buf to the file or socket associated with 
file_descriptor. 


e@ writevQ (Write to Descriptor Using Multiple Buffers) is used to write data to a file or socket 
descriptor. 


Note: These functions use header (include) files from the library QS YSINC, which is optionally installable. 
Make sure QSYSINC is installed on your system before using any of the functions. 
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accept()--Wait for Connection Request and Make 
Connection 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int accept (int socket_descriptor, 


struct sockaddr *address, 
int *address_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int accept (int socket_descriptor, 


struct sockaddr *address, 
socklen_t *address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


« 


The accept() function is used to wait for connection requests. accept() takes the first connection request on the queue of 
pending connection requests and creates a new socket to service the connection request. 


accept() is used with connection-oriented socket types, such as SOCK_STREAM. 


There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and syntax. The 
other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the 
UNIX 98 compatible interface with the _XOPEN_SOURCE macro. & 


Parameters 


socket_descriptor 
(Input) The descriptor of the socket on which to wait. 


address 


(Output) A pointer to a buffer of type struct sockaddr in which the address from which the connection request 
was received is stored. The structure sockaddr is defined in <sys/socket.h>. 


» The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. The sa_family field identifies the address family to which 
the address belongs, and sa_data is the address whose format is dependent on the address family. 


Note: See the usage notes about using different address families with sockaddr_storage. 


< 
address_length 


(Input/output) This parameter is a value-result field. The caller passes a pointer to the length of the address 
parameter. On return from the call, address_length contains the actual length of the address from which the 
connection request was received. 


Authorities 


When the socket identified by the socket_descriptor is of type AF_INET and a connection indication request is received 
over an APPC device, the thread must have adequate authority. The thread must have retrieve, insert, delete, and update 
authority to the APPC device. When the thread does not have this level of authority, an errno of EACCES is returned. 


Return Value 


accept() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e@ n (successful), where n is a socket descriptor. 


Error Conditions 


When accept() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 


A connection indication request was received on the socket referenced by the 
socket_descriptor parameter, but the process that issued the accept() did not have the 
appropriate privileges required to handle the request. The connection indication request is reset 
by the system. 


[EBADF] 


[ECONNABORTED] 


[EFAULT] 


[EINTR] 


[EINVAL] 


[EIO] 


[EMFILE] 


[ENFILE] 


[ENOBUFS] 


[ENOTSOCK] 


[EOPNOTSUPP] 


[EUNATCH] 


[EUNKNOWN] 


[EWOULDBLOCK] 


Descriptor not valid. 


Connection ended abnormally. 


An accept() was issued on a socket for which receives have been disallowed (due to a 
shutdown() call). 


This also could be encountered if time elapsed since a successful Rbind() is greater than the 
margin allowed by the associated SOCKS server. 


Bad address. 


System detected an address which was not valid while attempting to access the address or 
address_length parameters. 


Interrupted function call. 


Parameter not valid. 


This error code indicates one of the following: 


e@ The address_length parameter is set to a value that is less than zero, and the address 
parameter is set to a value other than a NULL pointer. 


e A listen() has not been issued against the socket referenced by the socket_descriptor 
parameter. 


Input/output error. 

Too many descriptions for this process. 

Too many descriptions in system. 

There is not enough buffer space for the requested operation. 

The specified descriptor does not reference a socket. 

Operation not supported. 

The socket_descriptor parameter references a socket that does not support the accept(). The 
accept() is only valid on sockets that are connection-oriented (for example, type of 
SOCK_STREAM). 

The protocol required to support the specified address family is not available at this time. 


Unknown system state. 


Operation would have caused the thread to be suspended. 


Error Messages 


Message ID 
CPE3418 E 
CPF9872 E 
CPFA081 E 


Error Message Text 
Possible APAR condition or hardware failure. 
Program or service program &1 in library &2 ended. Reason code &3. 


Unable to set return value or error code. 


Usage Notes 


1. If the address parameter is set to a NULL pointer or the address_length parameter points to an integer which has 
a value that is equal to zero, the address from which the connection request was received is not returned. 


2. If the length of the address to be returned exceeds the length of the address parameter, the returned address is 
truncated. 


3. The following are inherited by the descriptor returned by the accept() call: 


o. All socket options with a level of SOL_SOCKET. 


o The status flags: 


m Blocking flag (set/reset either by the ioctl() call with the FIONBIO request or by the fentl() call 
with the F_LSETFL command and the status flag set to O_.NONBLOCK). 


m Asynchronous flag (set/reset either by the ioctl() call with the FFOASYNC request or by the 
fentl() call with the F_LSETFL command and the status flag set to FASYNC). 


o. The process ID or process group ID that is to receive SIGIO or SIGURG signals (set/reset by either the 


ioctl() call with the FFOSETOWN or the SIOCSPGRP request, or by the fentl() call with the 
F_SETOWN command). 


4. Closing a socket causes any queued but unaccepted connection requests to be reset. 


5. The structure sockaddr is a generic structure used for any address family but it is only 16 bytes long. The 
actual address returned for some address families may be much larger. You should declare storage for the address 
with the structure sockaddr_storage. This structure is large enough and aligned for any protocol-specific 
structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the 
sockaddr_storage will always align with the family field of any protocol-specific structure. The BSD 4.3 
structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - sizeof (sa_family_t) ) 
#define _SS_ PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 


_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 


sa_family_t ss_family; 
char ss_padl1[_SS_PAD1SIZE]; 
char* _ss_align; 


wu 


, 


char ss_pad2[_SS_PAD2SIZE 


}; 
The BSD 4.4/UNIX 98 compatible structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - (sizeof (uint8_t) + 

sizeof (sa_family_t))) 

#define _SS PAD2SIZE (_SS_MAXSIZE - (sizeof (uint8_t) + sizeof(sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 


uint8_t ss_len; 

sa_family_t ss_family; 

char ss_padl1[_SS_PAD1SIZE]; 
char* _ss_align; 

char ss_pad2[_SS_PAD2SIZE]; 


}; 
<4 


6. If the socket is using an address family of AF_UNIX, the address (which is a path name) is returned in the default 
coded character set identifier (CCSID) currently in effect for the job. 


7. If the socket is using an address family of AF_UNIX_CCSID, the output structure sockaddr_unc defines the 
format and coded character set identifier (CCSID) of the address (which is a path name). 


8. If a successful Rbind() has been performed on the listening socket, then a new connection is not returned, but 
rather an inbound connection occurs on the same listening socket. The descriptor number returned is different, 
but it actually refers to the same connection referred to by the listening socket. 


9. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro 
defined to the value 520 or greater, the accept() API is mapped to gso_accept98().& 


Related Information 


e »>_XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface& 
e bind()--Set Local Address for Socket 

e fcntlQ--Perform File Control Command 

e ioctl()--Perform I/O Control Request 


e listenQ--Invite Incoming Connections Requests 


API Introduced: V3R1 
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accept_and_recv()--Wait for Connection Request and 
Receive the First Message That Was Sent 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int accept_and_recv(int listen_socket_descriptor, 
int *accept_socket_descriptor, 
struct sockaddr *remote_address, 
size_t *remote_address_length, 
struct sockaddr *local_address, 
size_t *local_address_length, 
void *buffer, 
size_t buffer_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int accept_and_recv(int listen_socket_descriptor, 
int *accept_socket_descriptor, 
struct sockaddr *remote_address, 
socklen_t *remote_address_length, 
struct sockaddr *local_address, 
socklen_t *local_address_length, 
void *buffer, 
size_t buffer_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


« 


The accept_and_recv() function is used to wait for an incoming connection request, receive the first message from the 
peer, and return the local and remote socket addresses associated with the connection. 


accept_and_recv() is used with connection-oriented sockets that have an address family of AF_INET% or AF_INET6 & 
and a socket type of SOCK_STREAM. 


The accept_and_recv() API is a combination of the accept(), getsockname(), and recv() socket APIs. Socket applications 
that use these three APIs can obtain improved performance by using accept_and_recv(). 


»> There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and syntax. The 
other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the 
UNIX 98 compatible interface with the _XOPEN_SOURCE macro. & 


Parameters 


listen_socket_descriptor 


(Input) The descriptor of the socket on which to wait. This parameter specifies the socket that has issued a 
successful call to listen(). 


accept_socket_descriptor 


(Input/Output) A pointer to an integer that specifies the socket descriptor on which to accept the incoming 
connection. This socket must not be bound or connected. The use of this parameter lets the application reuse the 
accepting socket. 


If a pointer to a value of -1 is passed in for this parameter, a new descriptor in the process's descriptor table will 
be allocated for incoming connection. The socket descriptor for a new connection will be returned to the 
application by this parameter. It is recommended that a value of -1 be used on the first call to accept_and_recv(). 
See the Usage Notes for additional information. 


remote_address 


(Output) A pointer to a buffer of type struct sockaddr in which the address from which the connection request 
was received is stored. The structure sockaddr is defined in <sys/socket.h>. 


» The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address family to 

which the address belongs, and sa_data is the address whose format is dependent on the address family. 

» Note: See the usage notes about using different address families with sockaddr_storage.& 
remote_address_length 


(Input/Output) This parameter is a value-result field. The caller passes a pointer to the length of the 
remote_address parameter. On return from the call, remote_address_length contains the actual length of the 
address from which the connection request was received. 


local_address 


(Output) A pointer to a buffer of type struct sockaddr in which the local address over which the connection 
request was received is stored. The structure sockaddr is defined in <sys/socket.h>. 


» The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address family to 
which the address belongs, and sa_data is the address whose format is dependent on the address family. 


» Note: See the usage notes about using different address families with sockaddr_storage.& 
local_address_length 


(Input/Output) This parameter is a value-result field. The caller passes a pointer to the length of the local_address 
parameter. On return from the call, local_address_length contains the actual length of the local address over 
which the connection request was received. 


buffer 


(Output) The pointer to the buffer in which the data that is to be read is stored. If a NULL pointer is passed in for 
this parameter, the receive operation is not performed and the accept_and_recv() function completes when the 
incoming connection is received. 


buffer_length 
(Input) The length in bytes of the buffer pointed to by the buffer parameter. 


Authorities 


If IP over SNA is being used, *CHANGE authority to the APPC device is required. 


Return Value 


accept_and_recv() returns an integer. Possible values are: 


e -1 (unsuccessful call) 


e n (successful call), where n is the number of bytes received. 


Error Conditions 


When accept_and_recv() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 


A connection indication request was received on the socket referenced by the 
listen_socket_descriptor parameter, but the process that issued the accept_and_recv() call did 
not have the appropriate privileges required to handle the request. The connection indication 
request is reset by the system. 


[EBADF] 


[ECONNABORTED] 


[EFAULT] 


[EINTR] 


[EINVAL] 


[EIO] 


[EISCONN] 


[EMFILE] 


[ENFILE] 


[ENOBUFS] 


[ENOTSOCK] 


Descriptor not valid. 


Either the listen_socket_descriptor or the descriptor pointed to by the accept_socket_descriptor 
parameter is not a valid socket descriptor. 


Connection ended abnormally. 


An accept_and_recv() was issued on a socket for which receive operations have been 
disallowed (due to a shutdown() call). 


Bad address. 
System detected an address that was not valid while attempting to access the 
accept_socket_descriptor, remote_address, remote_address_length, local_address, 


local_address_length, or buffer parameter. 


Interrupted function call. 


Parameter not valid. 


This error code indicates one of the following: 
e A listen() has not been issued against the socket referenced by the 
listen_socket_descriptor parameter. 


e@ The socket referenced by the accept_socket_descriptor parameter has been bound to a 
local address. 


e@ The accept_socket_descriptor does not have the same address family and socket type 
as the listen_socket_descriptor. 


e@ The accept_socket_descriptor parameter is set to a value that is less than -1. 


Input/output error. 


A connection has already been established. 


Too many descriptions for this process. 


Too many descriptions in system. 


There is not enough buffer space for the requested operation. 


The specified descriptor does not reference a socket. 


Either the listen_socket_descriptor or the descriptor pointed to by the accept_socket_descriptor 
parameter is not a valid socket descriptor. 


[EOPNOTSUPP] Operation not supported. 


This error code indicates one of the following: 


e@ The listen_socket_descriptor parameter references a socket that does not support the 
accept_and_recv() function. The accept_and_recv() function is only valid on sockets 
that have an address family of AF_INET or AF_INET6& and a socket type of 
SOCK_STREAM. 


e The O_NONBLOCK option is set for the listen_socket_descriptor or the descriptor 
pointed to by the accept_socket_descriptor parameter. Non-blocking is not supported 
for accept_and_recv(). 


[EUNATCH] The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. The accept_and_recv() function is only valid on sockets that have an address family of AF_INET % or 
AF_INET6& and a socket type of SOCK_STREAM. If the listen_socket_descriptor does not have the correct 
address family and socket type, -1 is returned and the errno value is set to EOPNOTSUPP. 


2. Non-blocking mode is not supported for this function. If O NONBLOCK is set on the listen_socket_descriptor 
parameter or on the descriptor pointed to by the accept_socket_descriptor parameter, -1 is returned and the errno 
value is set to EOPNOTSUPP. 


3. If the remote_address parameter is set to a NULL pointer, the address from which the connection request was 
received is not returned. If the length of the remote address to be returned exceeds the length that was specified 
by the remote_address_length parameter, the returned address will be truncated. 


4. If the local_address parameter is set to a NULL pointer, the local address to which the socket is bound is not 
returned. If the length of the local address to be returned exceeds the length that was specified by the 
local_address_length parameter, the returned address will be truncated. 


5. If the buffer parameter is set toa NULL pointer or the buffer_length parameter is set to value of 0, the receive 
operation is not performed and the accept_and_recv() function completes when the incoming connection is 
received. 


6. Ifa pointer to a value of -1 is passed in for the accept_socket_descriptor parameter, the following attributes are 
inherited by the socket descriptor that is returned by the accept_and_recv() call: 


o. All socket options with a level of SOL_SOCKET. 


o The status flags: 


m Asynchronous flag (set or reset either by the ioctl() call with the FIOASYNC request or by the 
fentl() call with the F_LSETFL command and the status flag set to FASYNC). 


o. The process ID or process group ID that is to receive SIGIO or SIGURG signals (set or reset by either the 
ioctl() call with the FFOSETOWN or the SIOCSPGRP request, or by the fenti() call with the 
F_SETOWN command). 


7. The accept_and_recv() function allows an application to reuse an existing socket descriptor. If a socket 
descriptor is specified for the accept_socket_descriptor parameter, it must not be bound or connected and it must 
have the same address family and socket type as the listen_socket_descriptor. The socket descriptor that is passed 
in for the accept_socket_descriptor parameter can be obtained by either calling socket() or by specifying the 
SF_REUSE flag on the flags parameter of the send_file() function. 


If an application specifies a pointer to an unbound and unconnected socket descriptor for the 
accept_socket_descriptor parameter that is the same address family and socket type as the 
listen_socket_descriptor, the accept_and_recv() function will try to use the accept_socket_descriptor for the 
incoming connection. If the accept_socket_descriptor cannot be used for the incoming connection, the descriptor 
for that socket will be closed and a new socket will be created for the incoming connection. The new socket may 
have a different descriptor number associated with it. This means that the value that is returned by the 
accept_socket_descriptor parameter may not be the same value that was specified by the application when the 
accept_and_recv() function was called. 


The ability to reuse an existing socket is not supported on all platforms. Therefore, it is recommended that a 
pointer to a value of -1 be passed in for the accept_socket_descriptor parameter. If socket reuse is not supported 
and the send_file() API is called with the flags parameter set to SF_REUSE, the socket connection will be closed 
and the socket descriptor will be set to -1 by the send_file() API. If socket reuse is supported, then the connection 
will be closed and the socket descriptor will be reset so that it can be used again. Regardless of whether socket 
reuse is supported or not, the application can pass its socket descriptor variable into the accept_and_recv() 
function as the accept_socket_descriptor parameter. 


8. #The structure sockaddr is a generic structure used for any address family but it is only 16 bytes long. The 
actual address returned for some address families may be much larger. You should declare storage for the address 
with the structure sockaddr_storage. This structure is large enough and aligned for any protocol-specific 
structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the 
sockaddr_storage will always align with the family field of any protocol-specific structure. 


The BSD 4.3 structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - sizeof (sa_family_t) ) 

#define _SS PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 


sa_family_t ss_family; 
char ss_pad1[_SS_PAD1SIZE]; 
char* _ss_align; 
char ss_pad2[_SS_PAD2SIZE]; 


}; 
The BSD 4.4/UNIX 98 compatible structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - (sizeof(uint8_t) + 
sizeof (sa_family_t))) 


#define _SS PAD2SIZE (_SS_MAXSIZE - (sizeof (uint8_t) + sizeof (sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 


uint8_t ss_len; 

sa_family_t ss_family; 

char ss_padl1[_SS_PAD1SIZE]; 
char* _ss_align; 

char ss_pad2[_SS_PAD2SIZE]; 


}; 
« 

9. To take full advantage of the performance improvement offered by the accept_and_recv() API, a multiple accept 
server model needs to be used by the application. In this model the server will do a socket(), bind(), and listen() 
as currently is done. The server will then give the listening socket to multiple jobs or threads. Each job or thread 
will then call accept_and_recv() using the same listening socket. When a connection request comes in, only one 
of the jobs or threads would wake up. 


10. If a successful Rbind() has been performed on the listening socket, then a new connection is not returned, but 
rather an inbound connection occurs on the same listening socket. The descriptor number returned is different, 
but it actually refers to the same connection referred to by the listening socket. 


11. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro 
defined to the value 520 or greater, the accept_and_recv() API is mapped to gso_accept_and_recv98().& 


Related Information 


e »_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface& 


@ accept()--Wait for Connection Request and Make Connection 


e getsockname()--Retrieve Local Address of Socket 


e@ recv()--Receive Data 


e send_file()--Send a File over a Socket Connection 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


bind()--Set Local Address for Socket 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int bind(int socket_descriptor, 


struct sockaddr *local_address, 
int address_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int bind(int socket_descriptor, 


const struct sockaddr *local_address, 
socklen_t address_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


% 


The bind() function is used to associate a local address with a socket. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro. * 


Parameters 


socket_descriptor 


(Input) The descriptor of the socket that is to be bound. 


local_address 


(Input) A pointer to a buffer of type struct sockaddr that contains the local address to which the 
socket is to be bound. The structure sockaddr is defined in <sys/socket.h>. 


= The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}i 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address 


family to which the address belongs, and sa_data is the address whose format is dependent on the 
address family. 


address_length 
(Input) The length of the local_address. 


Authorities 


e When the address type of the socket identified by the socket_descriptor is AF_INET, the thread 
must have retrieve, insert, delete, and update authority to the port specified by the local_address 
field. When the thread does not have this level of authority, an errno of EACCES is returned. 


e When the address type of the socket identified by the socket_descriptor is AF_INET and is 
running IP over SNA, the thread must have retrieve, insert, delete, and update authority to the 
APPC device. When the thread does not have this level of authority, an errno of EACCES is 
returned. 


Return Value 


bind() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e 0 (successful) 


Error Conditions 


When a bind() fails, errno can be set to one of the following: 


[EACCES] 


[EADDRINUSE] 


Permission denied. 


The process does not have the appropriate privileges to bind local_address to 
the socket pointed to by socket_descriptor (for example, if socket_descriptor is a 
socket with an address family of AF_INET, and the sockaddr_in structure 
(pointed to by local_address) specified a port that was restricted for use). 


Address already in use. 


This error code indicates one of the following: 


e The socket_descriptor points to a socket with an address family of 
AF_INET, and the address specified in the sockaddr_in structure 
(pointed to by local_address) has already been assigned to another 
socket. 


e The socket_descriptor points to a socket with an address family of 
AF_INET®6, and the address specified in the sockaddr_in6 structure 
(pointed to by local_address) has already been assigned to another 
socket. 


e The socket_descriptor points to a socket with an address family of 
AF_UNIX or AF_UNIX_CCSID, and the address specified in the 
sockaddr_un or sockaddr_unc structure (pointed to by /ocal_address) 
has already been assigned to another socket. 


[EADDRNOTAVAIL] Address not available. This error code indicates one of the following: 


[EAFNOSUPPORT] 


[EBADF] 


[EFAULT] 


e The socket_descriptor points to a socket with an address family of 
AF_INET,, and the IP address specified in the sockaddr_in structure 
(pointed to by local_address) is not one defined by the local interfaces. 


e = The socket_descriptor points to a socket with an address family of 
AF_INET6, and the IP address specified in the sockaddr_in6 structure 
(pointed to by local_address) is not one defined by the local interfaces. 


The type of socket is not supported in this protocol family. 


The address family specified in the address structure pointed to by 
local_address parameter cannot be used with the socket pointed to by the 
socket_descriptor parameter. 


Descriptor not valid. 


Bad address. 


The system detected an address which was not valid while attempting to access 
the local_address parameter. 


[EINVAL] 


[EIO] 


[ELOOP] 


Parameter not valid. This error code indicates one of the following: 


The address_length parameter specifies a length that is negative or is 
not valid for the address family. 


The socket referenced by socket_descriptor is not a socket of type 
SOCK_RAW and is already bound to an address. 


The local address pointed to by the local_address parameter specified 
an address that was not valid. 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the CCSID specified in sunc_gqlg in the 
sockaddr_unc structure (pointed to by /ocal_address) cannot be 
converted to the current default CCSID for integrated file system path 
names. 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and there was an incomplete character or shift state 
sequence at the end of sunc_path in the sockaddr_unc structure 
(pointed to by local_address). 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the sockaddr_unc structure (pointed to by 
local_address) was not valid: 


o The sunc_format was not set to SO.UNC_DEFAULT or 
SO_UNC_USE_QLG. 


o The sunc_zero was not initialized to zeros. 


oO The sunc_format field was set to SO_UNC_USE_QLG and the 
sunc_qlg structure was not valid: 


m The path type was less than 0 or greater than 3. 


m The path length was less than 0 or out of bounds. For 
example, a single-byte path name was greater than 126 
bytes or a double-byte path name was greater than 252 
bytes. 


m A reserved field was not initialized to zeros. 


Input/output error. 


A loop exists in symbolic links encountered during pathname resolution. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


[ENAMETOOLONG] | File name too long. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOENT] No such file or directory. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


[ENOSYS] Function not implemented. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID or AF_UNIX_CCSID address family. 


[ENOTDIR] Not a directory. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


[ENOTSOCK] The specified descriptor does not reference a socket. 

[EUNKNOWN] Unknown system state. 

[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. For sockets that use an address family of AF_UNIX or AF_UNIX_CCSID, the following is 
applicable: 


o The process must have the following types of permission: 


m Create permission to the directory in which the entry is to be created. 


m Search permission along all the components of the path. 


Also, processes trying to establish a connection with the connect() must have write access 
to the entry that is created. 


o For AF_UNIX, the path name is assumed to be in the default coded character set identifier 
(CCSID) currently in effect for the job. For AF_UNIX_CCSID, the path name is assumed 
to be in the format and CCSID specified in the sockaddr_unc (pointed to by 
local_address). 


o When the socket is no longer needed, the caller should remove the file system entry that 
was created by the bind() using the unlink() or QpOlunlinkQ system function. 


2. For sockets that use an address family of AF_INET, the following is applicable: 


oO The internet address structure sockaddr_in requires a 2-byte port number and a 32-bit IP 
address. You can have the system automatically select a port number by setting the port 
number to 0. 


#* The BSD 4.3 structure is: 


struct sockaddr_in { 
short sin_family; 
u_short sin_port; 
struct in_addr sin_addr; 
char sin_zero[8]; 


}; 
The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr_in { 


uint8_t sin_len; 
sa_family_t sin_family; 
u_short sin_port; 
struct in_addr sin_addr; 
char sin_zero[8]; 


by 


The BSD 4.4 sin_len field is the length of the address. * The sin_family is the address 
family (always AF_INET for TCP and UDP), sin_port is the port number, and sin_addr is 
the internet address. The sin_zero field is reserved and must be hex zeros. 


o A wildcard address is provided INADDR_ANY defined in <netinet/in.h>) that allows an 
application to receive messages directed to a specified port independent of the IP address 
that was specified. If a local IP address is specified, only data received on that IP address is 
made available. INADDR_ANY must be used to receive data from multiple local interface 
definitions. 


3. 2 For sockets that use an address family of AF_INET6, the following is applicable: 


oO The internet address structure sockaddr_in6 requires a 2-byte port number and a 128-bit IP 


address. You can have the system automatically select a port number by setting the port 
number to 0. 


The BSD 4.3 structure is: 


typedef unsigned short sa_family_t; 
typedef unsigned short in_port_t; 


struct sockaddr_in6é { 
sa_family_t sin6_family; 


in_port_t sin6_port; 
uint32_t sin6_flowinfo; 
struct in6_addr sin6_addr; 
uint32_t sin6_scope_id; 


hi; 
The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 
typedef unsigned short in_port_t; 


struct sockaddr_in6é { 


uint8_t sin6_len; 
sa_family_t sin6_family; 
in_port_t sin6_port; 
uint32_ t sin6_flowinfo; 
struct in6_addr sin6_addr; 
uint32_t sin6_scope_id; 


bh 


The BSD 4.4 sin6_len field is the length of the address. The sin6_family is the address 
family (AF_INET6 in this case), sin6_port is the port number, and sin6_addr is the internet 
address. The sin6_flowinfo field contains two pieces of information: the traffic class and 
the flow label. Note: This field is currently not supported and should be set to zero for 
upward compatibility. The sin6_scope_id field identifies a set of interfaces as appropriate 
for the scope of the address carried in the sin6_addr field. Note: This field is currently not 
supported and should be set to zero for upward compatibility. 


A wildcard address is provided that allows an application to receive messages directed to a 
specified port independent of the IP address that was specified. Since the IPv6 address type 
is a structure (struct in6_addr), a symbolic constant can be used to initialize an IPv6 
address variable, but cannot be used in an assignment. Therfore, the IPv6 wildcard address 
is provided in two forms as defined in <netinet/in.h>. The first version is a global variable 
named in6addr_any. This version is used similarly to the way applications use the 
INADDR_ANY in IPv4 as defined above and must be used for structure assignment. The 
other version is a symbolic constant named INGADDR_ANY_INIT. This version may be 
used to initialize an in6_addr structure. If a local IP address is specified, only data received 
on that IP address is made available. The wildcard address must be used to receive data 
from multiple local interface definitions. 


4. For sockets that use an address family of AF_TELEPHONY, the following is applicable: 


o A telephony address tel_addr consists of a 2-byte length followed by a telephone number 


up to 40 digits long. 


oO The telephony sockets address structure sockaddr_tel consists of the address family, the 
telephony address, and a reserved field. 


2* The BSD 4.3 structure is: 


struct tel_addr { 
unsigned short t_len; 
char t_addr[40]; 
}; 


struct sockaddr_tel { 


short stel_family; 
struct tel_addr stel_addr; 
char stel_zero[4]; 


be 


There is no BSD 4.4/UNIX 98 compatible structure defined for telephony addresses. 


The stel_family is the address family (always AF_TELEPHONY), the stel_addr is the 
telephone number length and the telephone number itself. The ste/_zero field is reserved. 


o A wildcard telephone number is provided (TELADDR_ANY defined in <nettel/tel.h>) 
that allows an application to answer calls directed to any of the local numbers specified in 
the connection list(s) associated with the device(s) that are being used by a socket. 


5. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the bind() API is mapped to 
qso_bind98().%& 


Related Information 


e@ = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


@ connect()--Establish Connection or Destination Address 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


close()--Close File or Socket Descriptor 


Syntax 


#include <unistd.h> 


int close(int fildes); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The close() function closes a descriptor, fildes. This frees the descriptor to be returned by future open() 
calls and other calls that create descriptors. 


When the last open descriptor for a file is closed, the file itself is closed. If the link count of the file is zero 
at that time, the space occupied by the file is freed and the file becomes inaccessible. 


close() unlocks (removes) all outstanding byte locks that a job has on the associated file. 


When all file descriptors associated with a pipe or FIFO special file are closed, any data remaining in the 
pipe or FIFO is discarded and internal storage used is returned to the system. 


When fildes refers to a socket, close() closes the socket identified by the descriptor. 


Parameters 


fildes 
(Input) The descriptor to be closed. 


Authorities 


No authorization is required. Authorization is verified during open(), creat(), or socket(). 


Return Value 


close() returns an integer. Possible values are: 


O  close() was successful. 


-1 closeQ was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If close() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


Permission denied. 
An attempt was made to access an object in a way forbidden by its object access permissions. 
The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations to file 
permissions at the server are not reflected at the client until updates to data that is stored locally by 
the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) Access to a remote file may 
also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote 
systems. 


[EAGAIN] 


Operation would have caused the process to be suspended. 


[EBADF] 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or a read or write 
request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is 
incorrect, or does not refer to an open file. 


[EBADFID] 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 
[EBUSY] 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 
[EDAMAGE] 


A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 
[EINTR] 


Interrupted function call. 
[EINVAL] 
The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and 
the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 
[EIO] 


Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 
#[EJRNDAMAGE] 
Journal damaged. 
A journal or all of the journal's attached journal receivers are damaged, or the journal sequence 


number has exceeded the maximum value allowed. This error occurs during operations that were 
attempting to send an entry to the journal. 


[EJRNENTTOOLONG] 
Entry too large to send. 


The journal entry generated by this operation is too large to send to the journal. 
[EJRNINACTIVE] 

Journal inactive. 

The journaling state for the journal is *INACTIVE. This error occurs during operations that were 

attempting to send an entry to the journal. 
[EJRNRCVSPC] 

Journal space or system storage error. 

The attached journal receiver does not have space for the entry because the storage limit has been 


exceeded for the system, the object, the user profile, or the group profile. This error occurs during 
operations that were attempting to send an entry to the journal. 


[ENEWJRN] 
New journal is needed. 
The journal was not completely created, or an attempt to delete it did not complete successfully. 


This error occurs during operations that were attempting to start or end journaling, or were 
attempting to send an entry to the journal. 


[ENEWJRNRCV] 
New journal receiver is needed. 


A new journal receiver must be attached to the journal before entries can be journaled. This error 
occurs during operations that were attempting to send an entry to the journal.*& 


[ENOBUFS] 


There is not enough buffer space for the requested operation. 
[ENOSPC] 
No space available. 
The requested operations required additional space on the device and there is no space left. This 
could also be caused by exceeding the user profile storage limit when creating or transferring 


ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOSYS] 


Function not implemented. 


An attempt was made to use a function that is not available in this implementation for any object or 
any arguments. 


The path name given refers to an object that does not support this function. 
[ENOTAVAIL] 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) 
processing. 


To recover from this error, wait until processing has completed for the independent ASP. 
[ENOTSAFE] 


Function is not allowed in a job that is running with multiple threads. 


[ESTALE] 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[EUNKNOWN] 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and 
correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 


[EADDRNOTAVAIL] 


Address not available. 


[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


The destination socket refused an attempted connect operation. 


[ECONNRESET] 


A connection with a remote socket was reset by that socket. 


[EHOSTDOWN] 


A remote host is not available. 


[EHOSTUNREACH] 


A route to the remote host is not available. 


[ENETDOWN] 


The network is not currently available. 


[ENETRESET] 


A socket is connected to a host that is no longer available. 


[ENETUNREACH] 


Cannot reach the destination network. 
[ESTALE] 
File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted 
at the server. 


[ETIMEDOUT] 


A remote host did not respond within the timeout period. 


[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
CPFA081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. Error number &1. 


Usage Notes 
1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

wg QNTC 

mw QSYS.LIB 

m {Independent ASP QSYS.LIB & 
gw QOPT 


2. When a socket descriptor is closed, the system tries to send any queued data associated with the 
socket. 


o For AF_NS or AF_INET sockets, depending on whether the SO_LINGER socket option is 
set, queued data may be discarded. 


Note: For these sockets, the default value for the SO_LINGER socket option has the option 
flag set off (the system attempts to send any queued data with an infinite wait time). 

o For AF_TELEPHONY sockets, depending on whether the SO_LINGER socket option is 
set, buffered data may be discarded. 
Note: For these sockets, the default value for the SO_LINGER socket option has the option 


flag set on with a time value of 1 second (the system will wait up to 1 second to send 
buffered data before clearing the telephone connection). 


3. A socket descriptor being shared among multiple processes is not closed until the process that 
issued the close() is the last process with access to the socket. 


Related Information 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


@ creat()--Create or Rewrite File 

e dupQ--Duplicate Open File Descriptor 

e dup2()--Duplicate Open File Descriptor to Another Descriptor 
e fcntlQ--Perform File Control Command 

@ open()--Open File 

e setsockopt()--Set Socket Options 


e unlinkQ--Remove Link to File 


Example 


The following example uses close() 


See Code disclaimer information for information pertaining to code examples. 


#include <stdio.h> 
#include <fcntl.h> 
#include <unistd.h> 


main() { 
int fdl, fd2; 
char out [20]="Test string", 
fn[]="test.file", 
in[20]; 
short write_error; 


memset (in, 0x00, sizeof(in)); 
write_error = 0; 


if ( (fdl = creat (fn,S_IRWXU)) == -1) 
perror ("creat() error"); 
else if ( (fd2 = open(fn,O_RDWR)) == -1) 
perror ("open() error"); 
else { 
if (write(fdl, out, strlen(out)+1) == -1) { 
perror ("write() error"); 
write_error = 1; 
} 
close(fdl1); 
if (!write_error) { 
if (read(fd2, in, sizeof(in)) == -1) 
perror("read() error"); 
else printf("string read from file was: '%Ss'\n", in); 
} 
close(fd2); 


} 
Output: 
string read from file was: 'Test string' 
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connect()--Establish Connection or Destination 
Address 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int connect (int socket_descriptor, 


struct sockaddr *destination_address, 
int address_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int connect (int socket_descriptor, 


const struct sockaddr *destination_address, 
socklen_t address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 
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The connect() function is used to establish a connection on a connection-oriented socket or establish the 
destination address on a connectionless socket. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


socket_descriptor 


(Input) The descriptor of the socket that is to be connected. 


destination_address 


(Input) A pointer to a buffer of type struct sockaddr that contains the destination address to which 
the socket is to be bound. The structure sockaddr is defined in <sys/socket.h>. 


= The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}i 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address 
family to which the address belongs, and sa_data is the address whose format is dependent on the 
address family. 


address_length 
(Input) The length of the destination_address. 


Authorities 


When the address type of the socket identified by the socket_descriptor is AF_INET and is running IP 
over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. When the 
thread does not have this level of authority, then an errno of EACCES is returned. 


Return Value 


connect() returns an integer. Possible values are: 
e -1 (unsuccessful) 


e 0 (successful) 


Error Conditions 


When a connect() fails, errno can be set to one of the following. For additional debugging information, see 
Debugging IP over SNA Configurations. 


[EACCES] 


[EADDRINUSE] 


Permission denied. 


This error code indicates one of the following: 


e The process does not have the appropriate privileges to connect to the 
address pointed to by the destination_address parameter. 


e The socket pointed to by socket_descriptor is using a 
connection-oriented transport service, and the destination_address 
parameter specifies a TCP/IP limited broadcast address (internet address 
of all ones). 


Address already in use. 


This error code indicates one of the following: 


e The socket_descriptor parameter points to a connection-oriented socket 
that has been bound to a local address that contained no wildcard values, 
and the destination_address parameter specified an address that 
matched the bound address. 


e The socket_descriptor parameter points to a socket that has been bound 
to a local address that contained no wildcard values, and the 
destination_address parameter (also containing no wildcard values) 
specified an address that would have resulted in a connection with a 
non-unique association. 


e For sockets with an address family of AF_TELEPHONY, the ISDN 
cause codes 0 and 17 are mapped to this errno. 


[EADDRNOTAVAIL] Address not available. 


[EAFNOSUPPORT] 


This error code indicates one of the following: 


e The socket_descriptor parameter points to a socket with an address 
family of AF_INET# or AF_INET6% and either a port was not 
available or a route to the address specified by the destination_address 
parameter could not be found. 


e For sockets with an address family of AF_TELEPHONY, the ISDN 
cause codes 16, 19, 21, 27, 31, and 102 are mapped to this errno. 


The type of socket is not supported in this protocol family. 


The address family specified in the address structure pointed to by 
destination_address parameter cannot be used with the socket pointed to by the 
socket_descriptor parameter. 


For sockets with an address family of AF_TELEPHONY, the ISDN cause codes 
49, 50, and 57 are mapped to this errno. 


[EALREADY] 


[EBADF] 


[ECONNREFUSED] 


[EFAULT] 


[EHOSTUNREACH] 


[EINPROGRESS] 


[EINTR] 


[EINVAL] 


Operation already in progress. 


A previous connect() function had already been issued for the socket pointed to 
by the socket_descriptor parameter, and has yet to be completed. This error code 
is returned only on sockets that use a connection-oriented transport service. 


Descriptor not valid. 


The destination socket refused an attempted connect operation. 


This error occurs when there is no application that is bound to the address 
specified by the destination_address parameter. 


For sockets with an address family of AF_TELEPHONY, the ISDN cause codes 
1, 2, 3, 6, and 7 are mapped to this errno. 


Bad address. 


The system detected an address which was not valid while attempting to access 
the destination_address parameter. 


A route to the remote host is not available. 


This error code is returned on sockets that use the AF_INET, #* AF_INET6*, 
and AF_TELEPHONY address families. 


For address family AF_TELEPHONY sockets, this error indicates that the 
default connection list entry was not available or that the call failed with one of 
the following ISDN cause codes: 18, 22, 26, 28, 29, or 30. 


Operation in progress. 


The socket_descriptor parameter points to a socket that is marked as 
nonblocking and the connection could not be completed immediately. This error 
code is returned only on sockets that use a connection-oriented transport service. 


Interrupted function call. 


Parameter not valid. 


This error code indicates one of the following: 


e The address_length parameter specifies a length that is negative or not 
valid for the address family. 


e@ The AF_INET# or AF_INET6% socket is of type SOCK_STREAM, 
and a previous connect() has already completed unsuccessfully. Only 
one connection attempt is allowed on a connection-oriented socket. 


Note: For sockets that have an address family of AF_UNIX, or 
AF_UNIX_CCSID, if a connect() fails, a subsequent connect() is 
allowed, even if the transport service being used is connection-oriented. 


@ connect() cannot be issued on the socket pointed to by the 
socket_descriptor parameter because the socket is using a 
connection-oriented transport service (with an address family of 
AF_INET#* or AF_INET6*&), and a shutdown() that disabled the 


sending of data was previously issued. 


e The destination address pointed to by the destination_address parameter 
specified an address that was not valid. 


e The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the CCSID specified in sunc_glg in the 
sockaddr_unc structure (pointed to by /ocal_address) cannot be 
converted to the current default CCSID for integrated file system path 
names. 


e The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and there was an incomplete character or shift state 
sequence at the end of sunc_path in the sockaddr_unc structure 
(pointed to by local_address). 


e The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the sockaddr_unc structure (pointed to by 
local_address) was not valid: 


o The sunc_format was not set to SO.UNC_DEFAULT or 
SO_UNC_USE_QLG. 


o The sunc_zero was not initialized to zeros. 


oO The sunc_format field was set to SO_UNC_USE_QLG and the 
sunc_qlg structure was not valid: 


m The path type was less than 0 or greater than 3. 


m The path length was less than 0 or out of bounds. For 
example, a single byte path name was greater than 126 
bytes or a double byte path name was greater than 252 
bytes. 


m A reserved field was not initialized to zeros. 


[EIO] Input/output error. 


[EISCONN] A connection has already been established. 


This error code is returned only on sockets that use a connection-oriented 
transport service. 


[ELOOP] A loop exists in symbolic links encountered during pathname resolution. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


[ENAMETOOLONG] | File name too long. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


[ENETDOWN] 


[ENETUNREACH] 


[ENOBUFS] 


[ENOENT] 


[ENOSYS] 


[ENOTDIR] 


[ENOTSOCK] 


[EOPNOTSUPP] 


[EPROTOTYPE] 


The network is not currently available. 


For sockets with an address family of AF_TELEPHONY, the ISDN cause codes 
81, 82, 83, 84, 85, 86, 88, 91, and 95 are mapped to this errno. 


Cannot reach the destination network. 


This error code indicates the following: 


e For sockets that use the AF_INET#* or AF_INET6%& address families, 
the address specified by the destination_address parameter requires the 
use of a router, and the socket option SO.DONTROUTE is currently set 
on. 


e For sockets with an address family of AF_TELEPHONY, the ISDN 
cause code 127 is mapped to this errno. 


There is not enough buffer space for the requested operation. 


For sockets with an address family of AF_TELEPHONY, the ISDN cause codes 
34, 38, 41, 42, 43, 44, 47, 58, and 63 are mapped to this errno. 


No such file or directory. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


Function not implemented. 


This error code is only returned on sockets that use the AF_UNIX , 
AF_UNIX_CCSID, AF_TELEPHONY address families. 


For sockets with an address family of AF_TELEPHONY, the ISDN cause codes 
65, 66, 69, 70, and 79 are mapped to this errno. 


Not a directory. 


The specified descriptor does not reference a socket. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


Operation not supported. 


connect() is not allowed on a passive socket (a socket for which a listen() has 
been done). 


For sockets with an address family of AF_TELEPHONY, the ISDN cause codes 
49, 50, and 57 are mapped to this errno. 


The socket type or protocols are not compatible. 


This error code is only returned on sockets that use the AF_UNIX or 
AF_UNIX_CCSID address family. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 


This error code is returned when connection establishment times out. No 
connection is established. A possible cause may be that the partner application is 
bound to the address specified by the destination_address parameter, but the 
partner application has not yet issued a listen(). 


[EUNKNOWN] Unknown system state. 

[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 

[EPROTO] An underlying protocol error has occurred. 


For sockets with an address family of AF_TELEPHONY, the ISDN cause codes 
96, 97, 98, 99, 100, 101, and 111 are mapped to this errno. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. connect() establishes an end-to-end connection. It can only be issued once on sockets that have an 
address family of AF_INET#* or AF_INET6%& and are of type SOCK_STREAM. (If the connect() 
fails to successfully establish the connection, you must close the socket and create a new socket if 
you wish to try to establish a connection again.) For sockets of other address families that are 
connection-oriented, you may simply try the connect() again to the same or to a new address. 
connect() can be issued on sockets of type SOCK_DGRAM and SOCK_RAW multiple times. Each 
time connect() is issued, it changes the destination address from which packets may be received and 
to which packets may be sent. 


Note: Issuing connect() on sockets of type SOCK_DGRAM and SOCK_RAW is not recommended 
because of dynamic route reassignment (picking a new route when a route that was previously used 
is no longer available). When this reassignment occurs, the next packet from the partner program 
can be received from a different IP address than the address your application specified on the 
connect(). This results in the data being discarded. 


2. When a connect() is issued successfully on sockets with an address family of AF_INET#* or 
AF_INET6% and type of SOCK_DGRAM, errors relating to the unsuccessful delivery of outgoing 
packets may be received as errno values. For example, assume an application has issued the 
connect() for a destination_address at which no server is currently bound for the port specified in 


destination_address, and the application sends several packets to that destination_address. 
Eventually, one of the application output functions (for example, send()) will receive an error 
[ECONNREFUSED]. If the application had not issued the connect(), this diagnostic information 
would have been discarded. 


. Aconnectionless transport socket for which a connect() has been issued can be disconnected by 
either setting the destination_address parameter to NULL or setting the address_length parameter 
to zero, and issuing another connect(). 


. For sockets that use a connection-oriented transport service and an address family of AF_INET 2 
or AF_INET6*& there is a notion of a directed connect. A directed connect allows two socket 
endpoints (socket A and socket B) to be connected without having a passive socket to accept an 
incoming connection request. The idea is for both sockets to bind to addresses. Socket A then 
issues a connect() specifying the address that socket B is bound to, and socket B issues a connect() 
specifying the address that socket A is bound to. At this point sockets A and B are connected, and 
data transfer between the sockets can now take place. 


. For sockets with an address family of AF_INET#* or AF_INET6%, the following is applicable: 


oO. For sockets of type SOCK_STREAM or SOCK_DGRAM, a local port number is implicitly 
assigned to the socket if the connect() is issued without previously issuing a bind(). 


. For sockets with an address family of AF_INET, the following is applicable: 


o If the destination address has an IP address that is set to zero, the system selects an 
appropriate destination IP address using the following algorithm: 


m If the socket is bound to an IP address of zero, a loopback address is used. If a 
loopback interface is not configured (or the associated interface is not active), the 
address of the next available interface that is active is used. Otherwise, the 
destination IP address is not changed (and results in an error on the connect()). 


m If the socket is bound to a nonzero IP address, then the IP address that the socket is 
bound to is used. 


o If the destination address has an internet IP address that is set to INADDR_ BROADCAST 
(hex OxFFFFFFFF), the system selects an appropriate destination IP address using the 
following algorithm: 


m If the socket is bound to an IP address of zero and: 


m It is using a connectionless transport service, then the first active interface 
found that supports broadcast frames is used by the networking software. 


m It is using a connection-oriented transport service, an error is returned 
([EACCES]). 


m If the socket is bound to a nonzero IP address and is using a connectionless 
transport service and: 


m The address that the socket is bound to denotes an interface that supports 
broadcast frames (for example, not a loopback address), then the limited 


broadcast address of the IP address that the socket is bound to is used. 


m The address that the socket is bound to is a loopback address, an error is 
returned ((EINVAL]). 


m If the socket is bound to a nonzero IP address and it is using a connection-oriented 
transport service, an error is returned ([EACCES]). 


7. For sockets with an address family of AF_UNIX or AF_UNIX_CCSID, the following is applicable: 


o There is no implicit binding of an address to the socket. The socket is unnamed if the 
connect() is issued without previously issuing a bind(). 


o The process must have write access to the destination address and search permission along 
all the components of the path. 


o For AF_UNIX, the path name is assumed to be in the default coded character set identifier 
(CCSID) currently in effect for the job. For AF_UNIX_CCSID, the path name is assumed 
to be in the format and coded character set identifier (CCSID) specified in the 
sockaddr_unc (pointed to by local_address). 


8. For sockets with an address family of AF_TELEPHONY, the following is applicable: 


o. If the connect() is issued without previously issuing a bind(), the socket is implicitly bound 
to a local address of TELADDR_ANY. 


o If the destination address is specified as TELADDR_ANY, the remote number contained in 
the out connection list entry of the connection list associated with the socket's first device 
will be used for the connect(). 


9, When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the connect() API is mapped to 
qso_connect98().*& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface** 


e fentlO--Perform File Control Command 


e ioctl)--Perform I/O Control Request 


e@ bind(--Set Local Address for Socket 


@ accept()--Wait for Connection Request and Make Connection 


e@ sendto()--Send Data 


e@ sendmsg()--Send Data or Descriptors or Both 


API introduced: V3R1 
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fcntl()--Perform File Control Command 


Syntax 


#include <sys/types.h> 
#include <unistd.h> 
#include <fcntl.h> 


int fentl(int descriptor, 
int command, 


-) 
Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The fentl(Q) function performs various actions on open descriptors, such as obtaining or changing the 
attributes of a file or socket descriptor. 


Parameters 


descriptor 


(Input) The descriptor on which the control command is to be performed, such as having its 
attributes retrieved or changed. 


command 


(Input) The command that is to be performed on the descriptor. 


(Input) A variable number of optional parameters that is dependent on the command. Only some of 
the commands use this parameter. 


The fcntl() commands that are supported are: 


F_DUPFD Duplicates the descriptor. A third int argument must be specified. fentl() returns the 
lowest descriptor greater than or equal to this third argument that is not already 
associated with an open file. This descriptor refers to the same object as descriptor and 
shares any locks. If the original descriptor was opened in text mode, data conversion is 
also done on the duplicated descriptor. The FD_CLOEXEC flag that is associated with 
the new descriptor is cleared. 


F_GETFD Obtains the descriptor flags for descriptor. fentlQ) returns these flags as its result. For a 
list of supported file descriptor flags, see Flags. Descriptor flags are associated with a 


single descriptor and do not affect other descriptors that refer to the same object. 


F_GETFL 


F_GETLK 


F_GETLK64 


F_GETOWN 


F_SETFD 


F_SETFL 


F_SETLK 


F_SETLK64 


F_SETLKW 


Obtains the file status flags and file access mode flags for descriptor. fentlQ returns 
these flags as its result. For a list of supported file status and file access mode flags, see 
Using the oflag Parameter in open().*& 


Obtains locking information for an object. You must specify a third argument of type 
struct flock *. See File Locking for details. fentlQ returns 0 if it successfully obtains the 
locking information. When you develop in C-based languages and the function is 
compiled with the LLARGE_FILES macro defined, F_GETLK is mapped to the 
F_GETLK64 symbol. 


Obtains locking information for a large file. You must specify a third argument of type 
struct flock64 *. See File Locking for details. fentlQ returns 0 if it successfully obtains 
the locking information. When you develop in C-based languages, it is necessary to 
compile the function with the LARGE_FILE_API macro defined to use this symbol. 


Returns the process ID or process group ID that is set to receive the SIGIO (I/O is 
possible on a descriptor) and SIGURG (urgent condition is present) signals. For more 
information, see Signal APIs. 


Sets the descriptor flags for descriptor. You must specify a third int argument, which 
gives the new file descriptor flag settings (see Flags). If any other bits in the third 
argument are set, fentl(Q) fails with the [EINVAL] error. fentl() returns 0 if it 
successfully sets the flags. Descriptor flags are associated with a single descriptor and 
do not affect other descriptors that refer to the same object. 


Sets status flags for the descriptor. You must specify a third int argument, giving the 
new file status flag settings (see Flags). fentlQ) does not change the file access mode, 
and file access bits in the third argument are ignored. All other oflag values that are 
valid on the open() API are also ignored. If any other bits in the third argument are set, 
fentl(Q fails with the [EINVAL] error. fentl(Q) returns 0 if it successfully sets the flags. 


Sets or clears a file segment lock. You must specify a third argument of type struct 
flock *. See File Locking for details. fentlQ returns 0 if it successfully clears the lock. 
When you develop in C-based languages and the function is compiled with the 
_LARGE_FILES macro defined, F_SETLK is mapped to the F_LSETLK64 symbol. 


Sets or clears a file segment lock for a large file. You must specify a third argument of 
type struct flock64 *. See File Locking for details. fentlQ returns 0 if it successfully 
clears the lock. When you develop in C-based languages, it is necessary to compile the 
function with the LLARGE_FILE_API macro defined to use this symbol. 


Sets or clears a file segment lock; however, if a shared or exclusive lock is blocked by 
other locks, fentl(Q) waits until the request can be satisfied. You must specify a third 
argument of type struct flock *. See File Locking for details. When you develop in 
C-based languages and the function is compiled with the LARGE_FILES macro 
defined, F_SETLKW is mapped to the F SETLKW64 symbol. 


F_SETLKW64 


F_SETOWN 


Flags 


Sets or clears a file segment lock on a large file; however, if a shared or exclusive lock 
is blocked by other locks, fentlQ) waits until the request can be satisfied. See File 


Locking for details. You must specify a third argument of type struct flock64 *. When 


you develop in C-based languages, it is necessary to compile the function with the 


_LARGE_FILE_API macro defined to use this symbol. 


Sets the process ID or process group ID that is to receive the SIGIO and SIGURG 
signals. For more information, see Signal APIs. 


There are several types of flags associated with each open objecte. Flags for an object are represented by 
symbols defined in the <fentl.h header file. The following file status flags can be associated with an object: 


FASYNC 


FNDELAY 


O_APPEND 


O_DSYNC 


O_NDELAY 


O_NONBLOCK 


#*O_RSYNC 


2O_SYNC 


The SIGIO signal is sent to the process when it is possible to do I/O. 
This flag is defined to be equivalent to O_NDELAY. 


Append mode. If this flag is 1, every write operation on the file begins at the end of 
the file. 


Synchronous update - data only. If this flag is 1, all file data is written to permanent 
storage before the update operation returns. Update operations include, but are not 
limited to, the following: ftruncate(), openQ) with O_TRUNC, and write(). 


This flag is defined to be equivalent to O_.NONBLOCK. 


Non-blocking mode. If this flag is 1, read or write operations on the file will not cause 
the thread to block. This file status flag applies only to pipe, FIFO, and socket 
descriptors. 


Synchronous read. If this flag is 1, read operations to the file will be performed 
synchronously. This flag is used in combination with O_SYNC or O_DSYNC. When 
O_RSYNC and O_SYNC are set, all file data and file attributes are written to 
permanent storage before the read operation returns. When O_RSYNC and 
O_DSYNC are set, all file data is written to permanent storage before the read 
operation returns.%& 


Synchronous update. If this flag is 1, all file data and file attributes relative to the I/O 
operation are written to permanent storage before the update operation returns. Update 
operations include, but are not limited to, the following: ftruncate(), open() with 
O_TRUNC, and write().*& 


The following file access mode flags can be associated with a file: 


O_RDONLY _ The file is opened for reading only. 
O_RDWR The file is opened for reading and writing. 


O_WRONLY The file is opened for writing only. 


A mask can be used to extract flags: 


O_ACCMODE Extracts file access mode flags. 


The following descriptor flags can be associated with a descriptor: 


FD_CLOEXEC Controls descriptor inheritance during spawn() and spawnp() when simple inheritance 
is being used, as follows: 


e Ifthe FD_CLOEXEC flag is zero, the descriptor is inherited by the child 
process that is created by the spawn() or spawnp()API. 


Note: Descriptors that are created as a result of the opendir() API (to 
implement open directory streams) are not inherited, regardless of the value of 
the FD_CLOEXEC flag. 


e Ifthe FD_CLOEXEC flag is set, the descriptor is not inherited by the child 
process that is created by the spawn() or spawnp() API. 


Refer to spawnQ--Spawn Process and spawnp()--Spawn Process with Path for additional information about 
FD_CLOEXEC. 


File Locking 


A local or remote job can use fentl() to lock out other local or remote jobs from a part of a file. By locking 
out other jobs, the job can read or write to that part of the file without interference from others. File locking 
can ensure data integrity when several jobs have a file accessed concurrently. For more information about 
remote locking, see information about the network lock manager and the network status monitor in the 


OS/400 Network File System Support book. 


Two different structures are used to control locking operations: struct flock and struct flock64 (both defined 
in the <fentl.h header file). You can use struct flock64 with the F. GETLK64, F_SETLK64, and 
F_SETLKW64 commands to control locks on large files (files greater than 2GB minus | byte). The struct 
flock structure has the following members: 


short 1_type 


short 1 whence 


off_t 1 start 
off_t l_len 
pid_t l_pid 


Indicates the type of lock, as indicated by one of the following symbols (defined 
in the <fentl.h> header file): 


F_RDLCK Indicates a read lock; also called a shared lock. When a job has a 
read lock, no other job can obtain write locks for that part of the 
file. More than one job can have a read lock on the same part of a 
file simultaneously. To establish a read lock, a job must have the 
file accessed for reading. 


F_WRLCK Indicates a write lock; also called an exclusive lock. When a job 
has a write lock, no other job can obtain a read lock or write lock 
on the same part or an overlapping part of that file. A job cannot 
put a write lock on part of a file if another job already has a read 
lock on an overlapping part of the file. To establish a write lock, a 
job must have accessed the file for writing. 


F_UNLCK Unlocks a lock that was set previously. 


One of three symbols used in determining the part of the file that is affected by 
this lock. These symbols are defined in the <unistd.h> header file and are the 
same as symbols used by Iseek(): 


SEEK _CUR_ The current file offset in the file. 
SEEK_END The end of the file. 
SEEK_SET The start of the file. 


Gives a byte offset used to identify the part of the file that is affected by this lock. 
If |_start is negative, it is handled as an unsigned value. The part of the file 
affected by the lock begins at this offset from the location given by |_whence. For 
example, if 1_whence is SEEK_SET and |_start is 10, the locked part of the file 
begins at an offset of 10 bytes from the beginning of the file. 


Gives the size of the locked part of the file, in bytes. If the size is negative, it is 
treated as an unsigned value. If l_len is zero, the locked part of the file begins at 
the position specified by |_whence and |_start, and extends to the end of the file. 
Together, 1_whence, |_start, and |_len are used to describe the part of the file that 
is affected by this lock. 


Specifies the job ID of the job that holds the lock. This is an output field used 
only with F_GETLK actions. 


void *l_reservedO Reserved. Must be set to NULL. 


void “*l_reserved1| 


Reserved. Must be set to NULL. 


When you develop in C-based languages and this function is compiled with _LARGE_FILES defined, the 
struct flock data type will be mapped to a struct flock64 data type. To use the struct flock64 data type 
explicitly, it is necessary to compile the function with _LARGE_FILE_API defined. 


The struct flock64 structure has the following members: 


short ]_type 


short 1_whence 


char 1_reserved2[4] 
off64_t 1_start 


off64_t 1_len 


pid_t 1_pid 

char reserved3[4] 
void *]_reservedO 
void *] reserved! 


Indicates the type of lock, as indicated by one of the following symbols 
(defined in the <fentl.h header file): 


F_RDLCK Indicates a read lock; also called a shared lock. When a job 
has a read lock, no other job can obtain write locks for that 
part of the file. More than one job can have a read lock on the 
same part of a file simultaneously. To establish a read lock, a 
job must have the file accessed for reading. 


F_WRLCK Indicates a write lock; also called an exclusive lock. When a 
job has a write lock, no other job can obtain a read lock or 
write lock on the same part or an overlapping part of that file. 
A job cannot put a write lock on part of a file if another job 
already has a read lock on an overlapping part of the file. To 
establish a write lock, a job must have accessed the file for 
writing. 


F_UNLCK Unlocks a lock that was set previously. 


One of three symbols used in determining the part of the file that is affected 
by this lock. These symbols are defined in the <unistd.h> header file and are 
the same as symbols used by Iseek(): 


SEEK_CUR_ The current file offset in the file. 
SEEK_END_ The end of the file. 
SEEK_SET The start of the file. 


Reserved field 


Gives a byte offset used to identify the part of the file that is affected by this 
lock. |_start is handled as a signed value. The part of the file affected by the 
lock begins at this offset from the location given by |_whence. For example, if 
1_whence is SEEK_SET and |_start is 10, the locked part of the file begins at 
an offset of 10 bytes from the beginning of the file. 


Gives the size of the locked part of the file, in bytes. If the size is negative, the 
part of the file affected is |_start + 1_len through |_start - 1. If 1_len is zero, the 
locked part of the file begins at the position specified by |_whence and |_start, 
and extends to the end of the file. Together, 1_whence, |_start, and |_len are 
used to describe the part of the file that is affected by this lock. 


Specifies the job ID of the job that holds the lock. This is an output field used 
only with F_GETLK actions. 


Reserved field. 
Reserved. Must be set to NULL. 


Reserved. Must be set to NULL. 


You can set locks by specifying F_SETLK or F_SETLK64 as the command argument for fentlQ). Such a 
function call requires a third argument pointing to a struct flock structure (or struct flock64 in the case of 
F_SETLK64), as in this example: 


struct flock lock_it; 

lock_it.l_type = F_RDLCK; 
lock_it.1l_whence = SEEK_SET; 

lock_it.l_ start = 0; 

lock_it.l_len = 100; 

fentl (file_descriptor,F_SETLK, é&élock_it); 


This example sets up a flock structure describing a read lock on the first 100 bytes of a file, and then calls 
fentl() to establish the lock. You can unlock this lock by setting 1_type to FLUNLCK and making the same 
call. If an F_SETLK operation cannot set a lock, it returns immediately with an error saying that the lock 
cannot be set. 


The F_SETLKW and F_SETLKW64 operations are similar to F_SETLK and F_SETLK64, except that 
they wait until the lock can be set. For example, if you want to establish an exclusive lock and some other 
job already has a lock established on an overlapping part of the file, fentlQ waits until the other process has 
removed its lock. 


F_SETLKW and F_SETLKW64 operations can encounter deadlocks when job A is waiting for job B to 
unlock a region and job B is waiting for job A to unlock a different region. If the system detects that an 
F_SETLKW or F_SETLKW64 might cause a deadlock, fentlQ fails with errno set to [EDEADLK]. 


With the F_SETLK64, F_SETLKW64, and F_GETLK64 operations, the maximum offset that can be 
specified is the largest value that can be held in an 8-byte, signed integer. 


A job can determine locking information about a file by using F_LGETLK and F_GETLK64 as the 
command argument for fentl(). In this case, the call to fentlQ should specify a third argument pointing to a 
flock structure. The structure should describe the lock operation you want. When fentl() returns, the 
structure indicated by the flock pointer is changed to show the first lock that would prevent the proposed 
lock operation from taking place. The returned structure shows the type of lock that is set, the part of the 
file that is locked, and the job ID of the job that holds the lock. In the returned structure: 


e |_whence is always SEEK_SET. 
e |_start gives the offset of the locked portion from the beginning of the file. 
e |_len is the length of the locked portion. 


If there are no locks that prevent the proposed lock operation, the returned structure has F_LUNLCK in 
1_type and is otherwise unchanged. 


If fentlQ) attempts to operate on a large file (one larger than 2GB minus | byte) with the F_SETLK, 
F_GETLK, or FSETLKW commands, the API fails with [EOVERFLOW]. To work with large files, 
compile with the LLARGE_FILE_API macro defined (when you develop in C-based languages) and use 
the F_SETLK64, F_GETLK64, or FSFETLKW64 commands. When you develop in C-based languages, it is 
also possible to work with large files by compiling the source with the LLARGE_FILES macro label 
defined. Note that the file must have been opened for large file access (either the open64() API was used or 
the open() API was used with the O_LLARGEFILE flag defined in the oflag parameter). 


An application that uses the F_LSETLK or F_SETLKW commands may try to lock or unlock a file that has 
been extended beyond 2GB minus 1 byte by another application. If the value of |_len is set to 0 on the lock 
or unlock request, the byte range held or released will go to the end of the file rather than ending at offset 
2GB minus 2. 


An application that uses the F_SETLK or F_SETLKW commands also may try to lock or unlock a file that 
has been extended beyond offset 2GB minus 2 with |_len NOT set to 0. If this application attempts to lock 

or unlock the byte range up to offset 2GB minus 2 and |_len is not 0, the unlock request will unlock the file 
only up to offset 2GB minus 2 rather than to the end of the file. 


A job can have several locks on a file at the same time, but only one type of lock can be set on a given byte. 


Therefore, if a job puts a new lock on a part of a file that it had locked previously, the job has only one lock 
on that part of the file. The type of the lock is the one specified in the most recent locking operation. 


Locks can start and extend beyond the current end of a file, but cannot start or extend ahead of the 
beginning of a file. 


All of the locks a job has on a file are removed when the job closes any descriptor that refers to the locked 
file. 


All locks obtained using fentlQ are advisory only. Jobs can use advisory locks to inform each other that 
they want to protect parts of a file, but advisory locks do not prevent input and output on the locked parts. If 
a job has appropriate permissions on a file, it can perform whatever I/O it chooses, regardless of what 
advisory locks are set. Therefore, advisory locking is only a convention, and it works only when all jobs 
respect the convention. 


Another type of lock, called a mandatory lock, can be set by a remote personal computer application. 
Mandatory locks restrict I/O on the locked parts. A read fails when reading a part that is locked with a 
mandatory write lock. A write fails when writing a part that is locked with a mandatory read or mandatory 
write lock. 


The maximum starting offset that can be specified by using the fnctl() API is 2° - 1, the largest number 
that can be represented by a signed 8-byte integer. Mandatory locks set by a personal computer application 
or by a user of the DosSetFileLocks64() API may lock a byte range that is greater than 23 - 1. 


An application that uses the F_LSETLK64 or F_LSETLKW64 commands can lock the offset range that is 
beyond 263 - 1 by locking offset 263 - 1. When offset 26 - 1 is locked, it implicitly locks to the end of the 
file. The end of the file is the largest number than can be represented by an 8-byte unsigned integer or 2° - 
1. This implicit lock may inhibit the personal computer application from setting mandatory locks in the 
range not explicitly accessable by the fcentlQ) API. 


Any lock set using the fentl() API that locks offset 26 - 1 will have a length of 0. 


An application that uses the F_GETLK64 may encounter a mandatory lock set by a personal computer 
application, which locks a range of offsets greater than 23 - 1. This lock conflict will have a starting offset 
equal to or less than 23 - 1 and a length of 0. 


Authorities 


No authorization is required. 


Return Value 


value fentl(Q was successful. The value returned depends on the command that was specified. 


-l fentlQ was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If fentlQ is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBADFUNC] 


[EBUSY] 


[EDAMAGE] 


[EDEADLK] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations 
to file permissions at the server are not reflected at the client until updates to data that 
is stored locally by the Network File System take place. (Several options on the Add 
Mounted File System (ADDMFS) command determine the time between refresh 
operations of local data.) Access to a remote file may also fail due to different 
mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. 


Operation would have caused the process to be suspended. 


The process tried to lock with F_LSETLK, but the lock is in conflict with a previously 
established lock. 


Descriptor not valid. 


A descriptor argument was out of range, referred to an object that was not open, or a 
read or write request was made to an object that is not open for that operation. 


A given descriptor or directory pointer is not valid for this operation. The specified 
descriptor is incorrect, or does not refer to an open object. 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as 
possible. 


Function parameter in the signal function is not set. 


A given descriptor or directory pointer is not valid for this operation. The specified 
descriptor is incorrect, or does not refer to an open object. 


Resource busy. 

An attempt was made to use a system resource that is not available at this time. 
A damaged object was encountered. 

A referenced object is damaged. The object cannot be used. 

Resource deadlock avoided. 


An attempt was made to lock a system resource that would have resulted in a 
deadlock situation. The lock was not obtained. 


The function attempted was failed to prevent a deadlock. 


[EFAULT] 


[EINVAL] 


[EIO] 


[EMFILE] 


[ENOLCK] 


[ENOMEM] 


[ENOSYS] 


[ENOTAVAIL] 


[ENOTSAFE] 


The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not 
valid. 


While attempting to access a parameter passed to this function, the system detected an 
address that is not valid. 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on 
an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 
Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 

Too many open files for this process. 


An attempt was made to open more files than allowed by the value of OPEN_MAX. 
The value of OPEN_MAX can be retrieved using the sysconf() function. 


The process has more than OPEN_MAX descriptors already open (see the sysconf() 
function). 


No locks available. 


A system-imposed limit on the number of simultaneous file and record locks was 
reached, and no more were available at that time. 


Storage allocation request failed. 

A function needed to allocate storage, but no storage is available. 
There is not enough memory to perform the requested function. 
Function not implemented. 


An attempt was made to use a function that is not available in this implementation for 
any object or any arguments. 


The path name given refers to an object that does not support this function. 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the independent 
ASP. 


Function is not allowed in a job that is running with multiple threads. 


[EOVERFLOW] Object is too large to process. 


[ESTALE] 


[EUNKNOWN] 


The object's data size exceeds the limit allowed by this function. 
One of the values to be returned cannot be represented correctly. 


The command argument is F_GETLK, F_SETLK, or FSSETLKW and the offset of 
any byte in the requested segment cannot be represented correctly in a variable of 
type off_t (the offset is greater than 2GB minus 1 byte). 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have 
been deleted at the server. 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could also indicate one of the 


following errors: 


[EADDRNOTAVAIL] Address not available. 


[ECONNABORTED] Connection ended abnormally. 


[ECONNREFUSED] The destination socket refused an attempted connect operation. 


[ECONNRESET] 


[EHOSTDOWN] 


A connection with a remote socket was reset by that socket. 


A remote host is not available. 


[EHOSTUNREACH] _ A route to the remote host is not available. 


[ENETDOWN] 


[ENETRESET] 


The network is not currently available. 


A socket is connected to a host that is no longer available. 


[ENETUNREACH] Cannot reach the destination network. 


[ETIMEDOUT] 


[EUNATCH] 


A remote host did not respond within the timeout period. 


The protocol required to support the specified address family is not available at 
this time. 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPFAO0D4 E File system error occurred. Error number &1. 
CPFA081 E Unable to set return value or error code. 
CPF3CF2 E Error(s) occurred during running of &1 API. 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 


oO Where multiple threads exist in the job. 


oO. The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m “Independent ASP QSYS.LIB & 
gw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB “File System Differences 


The following fentl() commands are not supported: 
o F_GETLK 
o F_SETLK 
o F_SETLKW 


Using any of these commands results in an [ENOSYS] error. 


3. Network File System Differences 


Reading and writing to a file with the Network File System relies on byte-range locking to 
guarantee data integrity. To prevent data inconsistency, use the fentl() API to get and release these 


locks. For more information about remote locking, see information about the network lock manager 


and the network status monitor in the OS/400 Network File System Su ort book. 
4. QNetWare File System Differences 


F_GETLK and F_SETLKW are not supported. F. RDLCK and F_WRLCK are ignored. All locks 
prevent reading and writing. Advisory locks are not supported. All locks are mandatory locks. 
Locking a file that is opened more than once in the same job with the same access mode is not 
supported, and its result is undefined. 


5. This function will fail with the [EOVERFLOW] error if the command is F_ GETLK, F_SETLK, or 
F_SETLKW and the offset or the length exceeds offset 2 GB minus 2. 


6. When you develop in C-based languages and an application is compiled with the LLARGE_FILES 
macro defined, the struct flock data type will be mapped to a struct flock64 data type. To use the 
struct flock64 data type explicitly, it is necessary to compile the function with the 
_LARGE_FILE_API defined. 


7. In several cases, similar function can be obtained by using ioct#l(). 


Related Information 


e The <sys/types.h> file (see Header Files for UNIX-Type Functions) 
e The <unistd.h> file (see Header Files for UNIX-Type Functions) 

e The <fentl.h> file (see Header Files for UNIX-Type Functions) 

e close()--Close File or Socket Descriptor 


e dupQ--Duplicate Open File Descriptor 

e dup2()--Duplicate Open File Descriptor to Another Descriptor 
e ioctl()--Perform I/O Control Request 

e lseek()--Set File Read/Write Offset 

@ open()--Open File 

@ spawn()--Spawn Process 

@ spawnp()--Spawn Process with Path 


e OS/400 Network File System Support book 


Example 


The following example uses fentl(): 


See Code disclaimer information for information pertaining to code examples. 


#include <stdio.h> 
#include <sys/types.h> 


#include <unistd.h> 
#include <fcntl.h> 


int main() 
{ 
int flags; 
int append_flag; 
int nonblock_flag; 
int access_mode; 
int file_descriptor; /* File Descriptor */ 
char *textl = "abcdefghij"; 
char *text2 = "0123456789"; 
char read_buffer[25]; 


memset (read_buffer, '\0O', 25); 


/* create a new file */ 

file_descriptor = creat ("testfile",S_IRWXU) ; 
write(file_descriptor, textl, 10); 
close(file_descriptor) ; 


/* open the file with read/write access */ 
file_descriptor = open("testfile", O_RDWR); 
read(file_descriptor, read_buffer, 24); 

printf ("first read is \'%s\'\n", read_buffer) ; 


/* reset file pointer to the beginning of the file */ 
lseek(file_descriptor, 0, SEEK_SET); 

/* set append flag to prevent overwriting existing text */ 
fentl(file_descriptor, F_SETFL, O_APPEND); 
write(file_descriptor, text2, 10); 

lseek(file_descriptor, 0, SEEK_SET); 

read(file_descriptor, read_buffer, 24); 

printf ("second read is \'%s\'\n",read_buffer) ; 


close(file_descriptor) ; 
unlink ("testfile") ; 


return 0; 


} 


Output: 


first read is ‘abcdefghij' 
second read is 'abcdefghij0123456789' 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


fstat()--Get File Information by Descriptor 


Syntax 


#include <sys/stat.h> 


int fstat(int descriptor, 
struct stat *buffer) 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The fstat() function gets status information about the object specified by the open descriptor descriptor and 
stores the information in the area of memory indicated by the buffer argument. The status information is 
returned in a stat structure, as defined in the <sys/stat.h> header file. 


Parameters 


descriptor 


(Input) The descriptor for which information is to be retrieved. 


buffer 


(Output) A pointer to a buffer of type struct stat in which the information is returned. The structure 
pointed to by the buffer parameter is described in statQ)-- Get File Information. 


The st_mode, st_dev, and st_blksize fields are the only fields set for socket descriptors. The 
st_mode field is set to a value that indicates the descriptor is a socket descriptor, the st_dev field is 
set to -1, and the st_blksize field is set to an optimal value determined by the system. 


Authorities 


No authorization is required. 


Return Value 


O  fstat() was successful. The information is returned in buffer. 


-1_ fstatQ) was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If fstat() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBADFUNC] 


[EBUSY] 


[EDAMAGE] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations 
to file permissions at the server are not reflected at the client until updates to data that 
is stored locally by the Network File System take place. (Several options on the Add 
Mounted File System (ADDMFS) command determine the time between refresh 
operations of local data.) Access to a remote file may also fail due to different 
mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. 


Operation would have caused the process to be suspended. 


Descriptor not valid. 


A descriptor argument was out of range, referred to a file that was not open, or a read 
or write request was made to a file that is not open for that operation. 


A given descriptor or directory pointer is not valid for this operation. The specified 
descriptor is incorrect, or does not refer to an open object. 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as 
possible. 


Function parameter in the signal function is not set. 


A given descriptor or directory pointer is not valid for this operation. The specified 
descriptor is incorrect, or does not refer to an open object. 


Resource busy. 
An attempt was made to use a system resource that is not available at this time. 
A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not 
valid. 


While attempting to access a parameter passed to this function, the system detected an 
address that is not valid. [EFAULT] is returned if this function is passed a pointer 
parameter that is not valid. 


[EINVAL] The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on 
an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 
This error code may be returned when the underlying object represented by the 
descriptor is unable to fill the stat structure (for example, if the function was issued 
against a socket descriptor that had its connection reset). 

[EIO] Input/output error. 
A physical I/O error occurred. 


A referenced object may be damaged. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOSYSRSC] System resources not available to complete request. 


[ENOTAVAIL] Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the independent 
ASP. 


[ENOTSAFE] Function is not allowed in a job that is running with multiple threads. 


[EOVERFLOW] Object is too large to process. 
The object's data size exceeds the limit allowed by this function. 


The specified file exists and its size is too large to be represented in the structure 
pointed to by buffer (the file is larger than 2GB minus 1 byte). 


[EPERM] Operation not permitted. 


You must have appropriate privileges or be the owner of the object or other resource 
to do the requested operation. 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have 
been deleted at the server. 


[EUNATCH] 


[EUNKNOWN] 


The protocol required to support the specified address family is not available at this 
time. 
Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could also indicate one of the 


following errors: 


[EADDRNOTAVAIL] Address not available. 


[ECONNABORTED] Connection ended abnormally. 


[ECONNREFUSED] The destination socket refused an attempted connect operation. 


[ECONNRESET] 


[EHOSTDOWN] 


A connection with a remote socket was reset by that socket. 


A remote host is not available. 


[EHOSTUNREACH] _ A route to the remote host is not available. 


[ENETDOWN] 


[ENETRESET] 


The network is not currently available. 


A socket is connected to a host that is no longer available. 


[ENETUNREACH] Cannot reach the destination network. 


[ETIMEDOUT] 


A remote host did not respond within the timeout period. 


Error Messages 


The following messages may be sent from this function: 


Message ID 
CPFA0D4 E 
CPFA081 E 
CPF3CF2 E 
CPE3418 E 


Error Message Text 

File system error occurred. Error number &1. 
Unable to set return value or error code. 
Error(s) occurred during running of &1 API. 


Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when both of the following conditions occur: 


oO Where multiple threads exist in the job. 


oO The object this function is operating on resides in a file system that is not threadsafe. Only 
the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m Independent ASP QSYS.LIB & 
mw QOPT 


2. Sockets-Specific Notes 


oO The field st_mode can be inspected using the S_ISSOCK macro (defined in <sys/stat.h>) 
to determine if the descriptor is pointing to a socket descriptor. 


oO For socket descriptors, use the send buffer size (this is the value returned for st_blksize) for 
the length parameter on your input and output functions. This can improve performance. 


Note: IBM reserves the right to change the calculation of the optimal send size. 
3. QOPT File System Differences 


The value for st_atime will always be zero. The value for st_ctime will always be the creation date 
and time of the file or directory. 


The user, group, and other mode bits are always on for an object that exists on a volume not 
formatted in Universal Disk Format (UDF). 


fstat on /QOPT will always return 2,147,483,647 for size fields. 
fstat on optical volumes will return the volume capacity or 2,147,483,647, whichever is smaller. 


The file access time is not changed. 


4. Network File System Differences 


Local access to remote files through the Network File System may produce unexpected results due 
to conditions at the server. Once a file is open, subsequent requests to perform operations on the 
file can fail because file attributes are checked at the server on each request. If permissions on the 
file are made more restrictive at the server or the file is unlinked or made unavailable by the server 
for another client, your operation on an open descriptor will fail when the local Network File 
System receives these updates. The local Network File System also impacts operations that retrieve 
file attributes. Recent changes at the server may not be available at your client yet, and old values 


may be returned from operations. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) 


5. QNetWare File System Differences 


The QNetWare file system does not fully support mode bits. See the Netware on iSeries topic for 
more information. 
6. This function will fail with the [EOVERFLOW] error if the specified file exists and its size is too 


large to be represented in the structure pointed to by buffer (the file is larger than 2GB minus 1 
byte). 


7. When you develop in C-based languages and this function is compiled with [LARGE _FILES 
defined, it will be mapped to fstat64(). Note that the type of the buffer parameter, struct stat *, also 
will be mapped to type struct stat64 *. See stat64Q for more information on this structure. 


Related Information 


e The <sys/types.h> file (see Header Files for UNIX-Type Functions) 


e The <sys/stat.h> file (see Header Files for UNIX-Type Functions) 


e fentlQ--Perform File Control Command 

e fstat64Q--Get File Information by Descriptor (Large File Enabled) 
e |statQ--Get File or Link Information 

@ open()--Open File 

e socket()--Create Socket 

e stat()--Get File Information 

e stat64()--Get File Information (Large File Enabled)) 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example gets status information: 


#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <stdio.h> 
#include <time.h> 


main() { 


char fn[]="temp.file"; 


struct 


stat info; 


int file_descriptor; 


if ((file_descriptor = creat(fn, S_IWUSR)) < 0) 
perror ("creat() error"); 


else { 


if (fstat(file_descriptor, &info) != 0) 
perror("fstat() error"); 

else { 
puts ("fstat() returned:"); 
printf(" inode: Sda\n", (int) info.st_ino); 
printf (" dev id: Sda\n", (int) info.st_dev); 
printf (" mode: 308x\n", info.st_mode) ; 
printf(" links: Sda\n", info.st_nlink); 
printf (" uid: Sda\n", (int) info.st_uid); 
printt(" gid: Sda\n", (int) info.st_gid); 


} 
close (file_descriptor) ; 
unlink (fn); 


} 


Output: Note that the output may vary from system to system. 


fstat() returned: 
inode: 3057 
dev id: 1 
mode: 03000080 
links: 1 
uid: 13:7] 
gid: 500 
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getdomainname()--Retrieve Domain Name 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int getdomainname(char *name, 
int length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The getdomainname() function is used to retrieve the name of the domain from the system. 


Parameters 


name 
(Output) The name parameter can be one of the following: 


o The pointer to a character array where the domain name is to be stored. The domain name 
is NULL-terminated unless the length of the domain name exceeds the length of the name 
parameter. In that case the domain name is truncated to the size of the name parameter. 


o ANULL string when a sethostname() has not been previously issued since the last initial 


program load. 


length 


(Input) The length of the name parameter. Maximum length of domain names is 255. 


Return Value 


getdomainname() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e 0 (successful) 


Error Conditions 


When getdomainname() fails, errno can be set to one of the following: 
[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
name parameter. 


[EINVAL] Parameter not valid. 
The /ength parameter specifies a negative value. 


[EIO] Input/output error. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. When a process issues a setdomainname(), the name of the domain can be accessed by any process 
that issues a getdomainname(). 


2. The name of the domain is reset to NULL when an initial program load is performed. 


Note: The domain name returned by this function is NOT 
related to the domain name of the domain name server that is 
configured using the Configure TCP/IP (CFGTCP) menu. 


3. The domain name is returned in the default coded character set identifier (CCSID) currently in 
effect for the job. 


Related Information 


e@ setdomainname()--Set Domain Name 
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gethostid()--Retrieve Host ID 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int gethostid() 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The gethostid() function is used to retrieve a host's ID. 


Return Value 


gethostid() returns an integer. Possible values are: 


e@ 0 when a sethostid() has not been issued previously since the last initial program load (IPL) 


e n (successful), where n is the number specified on a previously issued sethostid() call 


Usage Notes 


1. When a process issues a sethostid(), the host_id can be accessed by any process that issues a 
gethostid() 


2. The host_id is reset to zero when an initial program load is performed. 


3. The host_id is a signed integer. Therefore, a -1 return value from the gethostid() may not indicate 
an error, but rather that a previous sethostid() was issued that specified a host_id of -1. 


4. While many socket implementations refer to the host_id as the IP address of the machine, this is not 
necessarily the case. Many machines that support the TCP/IP protocol suite support multiple local 
IP addresses. The value contained in host_id is not used by TCP in any manner. 


Related Information 


e sethostid()--Set Host ID Address 


e gethostname()--Retrieve Host Name 


e sethostname()--Set Host Name 
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gethostname()--Retrieve Host Name 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int gethostname(char *name, 
int length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int gethostname(char *name, 
socklen_t length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


% 


The gethostname() function is used to retrieve the name of the host from the system. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_ SOURCE macro. * 


Parameters 


name 


(Output) The pointer to a character array where the host name is to be stored. The host name is 
NULL-terminated unless the length of the host name exceeds the length of the name parameter, in 
which case the host name is truncated to the size of the name parameter. 


length 
(Input) The length of the name parameter. 


Authorities 


No authorization is required. 


Return Value 


gethostname() returns an integer. Possible values are: 


e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When gethostname() fails, errno can be set to one of the following: 
[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
name parameter. 


[EINVAL] Parameter not valid. 

The length parameter specifies a negative value. 
[EIO] Input/output error. 
[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. Maximum length of host names is defined by {MAXHOSTNAMELEN } (defined in 
<sys/param.h>). 


2. When a process issues a sethostname(), the host name can be accessed by any process that issues a 
gethostname(). 


3. Onan initial program load, the host name is set to whatever was configured using the iSeries 
Navigator or “& option 12 (Change TCP/IP domain information) on the Configure TCP/IP 
(CFGTCP) menu. The local domain name is appended with the local host name and stored in 
system-wide storage. This combined name is the host name that can be retrieved by gethostname(). 
If the local host name and local domain name are not set, the host name is set to NULL. 


4. The host name is returned in the default coded character set identifier (CCSID) currently in effect 
for the job. 


5. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the gethostname() API is mapped to 
qso_gethostname98().%& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e sethostname()--Set Host Name 


e gethostid(Q--Retrieve Host ID Address 


e sethostidQ--Set Host ID Address 
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getpeername()--Retrieve Destination Address of 
Socket 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int getpeername(int socket_descriptor, 


struct sockaddr *destination_address, 
int *address_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int getpeername(int socket_descriptor, 


struct sockaddr *destination_address, 
socklen_t *address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


« 


The getpeername() function is used to retrieve the destination address to which the socket is connected. 


» There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and syntax. The 
other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the 
UNIX 98 compatible interface with the _XOPEN_SOURCE macro. & 


Parameters 


socket_descriptor 


(Input) The descriptor of the socket for which the destination address is to be retrieved. 


destination_address 


(Output) A pointer to a buffer of type struct sockaddr in which the destination address to which the socket 
connects is stored. The structure sockaddr is defined in <sys/socket.h>. 


» The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address family to 
which the address belongs, and sa_data is the address whose format is dependent on the address family. 


» Note: See the usage notes about using different address families with sockaddr_storage. 


< 
address_length 


(I/O) This parameter is a value-result field. The caller passes a pointer to the length of the destination_address 
parameter. On return from the call, the address_length parameter contains the actual length of the destination 
address. 


Authorities 


No authorization is required. 


Return Value 


getpeername() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e 0 (successful) 


Error Conditions 


When getpeername() fails, errno can be set to one of the following: 


[EBADF] Descriptor not valid. 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
destination_address or address_length parameters. 


[EINVAL] Parameter not valid. 


The address_length parameter specifies a negative value. 


[EIO] 


Input/output error. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTCONN] _ Requested operation requires a connection. 


[ENOTSOCK] _ The specified descriptor does not reference a socket. 


[EUNKNOWN]_ Unknown system state. 


[EUNATCH] The protocol required to support the specified address family is not available at this time. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. 


2. 


getpeername() fails if issued against a socket for which a connect() has not been done. 


For connection oriented sockets, getpeername() fails if both the write side and the read side have been closed 
through the use of one or more previous shutdown() functions. 


. If the length of the address to be returned exceeds the length of the destination_address parameter, the returned 


address is truncated. 


. The structure sockaddr is a generic structure used for any address family but it is only 16 bytes long. The 


actual address returned for some address families may be much larger. You should declare storage for the address 
with the structure sockaddr_storage. This structure is large enough and aligned for any protocol-specific 
structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the 
sockaddr_storage will always align with the family field of any protocol-specific structure. 


The BSD 4.3 structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_ PADISIZE (_SS_ALIGNSIZE - sizeof (sa_family_t) ) 

#define _SS_ PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 
sa_family_t ss_family; 
char ss_padl1[_SS_PAD1SIZE]; 


char* _ss_align; 
char ss_pad2[_SS_PAD2SIZE]; 


}; 
The BSD 4.4/UNIX 98 compatible structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - (sizeof (uint8_t) + 

sizeof (sa_family_t))) 

#define _SS PAD2SIZE (_SS_MAXSIZE - (sizeof (uint8_t) + sizeof (sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 


uint8_t ss_len; 

sa_family_t ss_family; 

char ss_pad1[_SS_PAD1SIZE]; 
char* _ss_align; 

char ss_pad2[_SS_PAD2SIZE]; 


}; 
<4 


5. When used with an address family of AF_UNIX or AF_UNIX_CCSID, getpeername() always returns the same 
path name that was specified on the bind() in the peer program. If the path name specified by the peer program 
was not a fully qualified path name, the output of getpeername() is meaningful only if your program knows what 
current directory was in effect for the peer program when it issued the bind(). For AF_UNIX, the path name is 
returned in the default coded character set identifier (CCSID) currently in effect for the job. For 
AF_UNIX_CCSID, the output structure sockaddr_unc defines the format and CCSID of the returned path name. 


6. For sockets with an address family of AF_TELEPHONY, the following is applicable: 
o For the active (connecting) end of a connection, getpeername() will return the number dialed. 


o For the passive (accepting) end of a connection, getpeername() will return the number of the caller, if 
available. Otherwise, it will return TELADDR_ANY. 


7. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro 
defined to the value 520 or greater, the getpeername() API is mapped to qso_getpeername98().& 


Related Information 


e »>_XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface& 


@ accept()--Wait for Connection Request and Make Connection 


e@ bind(--Set Local Address for Socket 


e connect()--Establish Connection or Destination Address 


e@ getsockname()--Retrieve Local Address of Socket 
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getsockname()--Retrieve Local Address of Socket 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int getsockname(int socket_descriptor, 


struct sockaddr *local_address, 
int *address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int getsockname(int socket_descriptor, 
struct sockaddr *local_address, 
socklen_t *address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


« 


The getsockname() function is used to retrieve the local address associated with the socket. 


» There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and syntax. The 
other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the 
UNIX 98 compatible interface with the _XOPEN_SOURCE macro. & 


Parameters 


socket_descriptor 
(Input) The descriptor of the socket for which the local address is to be retrieved. 


local_address 


(Output) A pointer to a buffer of type struct sockaddr in which the local address of the socket is stored. The 
structure sockaddr is defined in <sys/socket.h>. 


» The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address family to 
which the address belongs, and sa_data is the address whose format is dependent on the address family. 


» Note: See the usage notes about using different address families with sockaddr_storage.& 
address_length 


(I/O) This parameter is a value-result field. The caller passes a pointer to the length of the local_address 
parameter. On return from the call, the address_length parameter contains the actual length of the local address. 
Authorities 


No authorization is required. 


Return Value 


getsockname() returns an integer. Possible values are: 


e -1! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When getsockname() fails, errno can be set to one of the following: 


[EBADF] Descriptor not valid. 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the local_address or 
address_length parameters. 


[EINVAL] Parameter not valid. This error code indicates one of the following: 
e The address_length parameter specifies a negative value. 


e The socket specified by the socket_descriptor parameter is using a connection-oriented 
transport service and either the write-side has been shut down (with a shutdown()) or the 
connection has been reset. 


[EIO] Input/output error. 

[ENOBUFS] There is not enough buffer space for the requested operation. 
[ENOTSOCK] _ The specified descriptor does not reference a socket. 
[EUNKNOWN]_ Unknown system state. 


[EUNATCH] The protocol required to support the specified address family is not available at this time. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. If the length of the address to be returned exceeds the length of the local_address parameter, the returned address 
will be truncated. 


2. The structure sockaddr is a generic structure used for any address family but it is only 16 bytes long. The 
actual address returned for some address families may be much larger. You should declare storage for the address 
with the structure sockaddr_storage. This structure is large enough and aligned for any protocol-specific 
structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the 
sockaddr_storage will always align with the family field of any protocol-specific structure. 


The BSD 4.3 structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - sizeof (sa_family_t) ) 

#define _SS_ PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 
sa_family_t ss_family; 


pn 


char ss_pad1[_SS_PAD1SIZE 
char* _ss_align; 
char ss_pad2[_SS_PAD2SIZE]; 


, 


}; 
The BSD 4.4/UNIX 98 compatible structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - (sizeof (uint8_t) + 

sizeof (sa_family_t))) 

#define _SS PAD2SIZE (_SS_MAXSIZE - (sizeof (uint8_t) + sizeof (sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


~~ 


struct sockaddr_storage { 


uint8_t ss_len; 

sa_family_t ss_family; 

char ss_pad1l[_SS_PAD1SIZE]; 
char* _ss_align; 

char ss_pad2[_SS_PAD2SIZE]; 


}; 
<4 


3. When used with an address family of AF_UNIX or AF_UNIX_CCSID, getsockname() always returns the same 
path name that was specified on a bind(). If the path name that was specified is not a fully qualified path name, 
the output of getsockname() is meaningful only if your program knows what current directory was in effect at the 
time of the bind(). For AF_UNIX, the path name is returned in the default coded character set identifier (CCSID) 
currently in effect for the job. For AF_UNIX_CCSID, the output structure sockaddr_unc defines the format and 
CCSID of the returned path name. 


4. getsockname() produces different results, depending on the address family or type of the socket: 
o For address family of AF_INET: 


m If the type is SOCK_STREAM or SOCK_DGRAM, getsockname() will return 0 if issued before 
the bind(). The socket address that is returned has the IP address and port number fields set to 
Zeros. 


a If the type is SOCK_RAW, getsockname() returns a -1 if issued before a bind(). 
m If the type is SOCK_STREAM, and an Rbind() has successfully completed, then the address 
returned is the SOCKS server address. See Rbind() for more information. 
o For address family of AF_INET6: 


m If the type is SOCK_STREAM or SOCK_DGRAM, getsockname() will return 0 if issued before 
the bind(). The socket address that is returned has the IP address and port number fields set to 
Zeros. 


m If the type is SOCK_RAW, getsockname() returns a -1 if issued before a bind(). & 


o For address family of AF_UNIX or AF_UNIX_CCSID, getsockname() returns 0 if issued before a bind(). 
The address length is 0. This is always the case for sockets created by socketpair(). 


5. For address family of AF_TELEPHONY: 
o If issued before the bind(), getsockname() will return 0. 
o If issued after a successful bind(), getsockname() will return the bound address. 


o If issued after a connection has been established, the address returned depends on which end of the 
connection is being queried. For the active (connecting) end, getsockname() will return the bound 
address. For the passive (accepting) end, getsockname() will return the called address, if available. 
Otherwise, it will return the bound address. 


6. #*When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro 
defined to the value 520 or greater, the getsockname() API is mapped to qso_getsockname98().& 


Related Information 


e »>_XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface& 


e@ bind(--Set Local Address for Socket 


e@ connect()--Establish Connection or Destination Address 
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getsockopt()--Retrieve Information about 
Socket Options 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int getsockopt (int socket_descriptor, 
int level, 
int option_name, 


char *option_value, 
int *option_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int getsockopt (int socket_descriptor, 
int level, 
int option_name, 


void *option_value, 
socklen_t *option_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


= 


The getsockopt() function is used to retrieve information about socket options. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_ SOURCE macro. *& 


Parameters 


socket_descriptor 


(Input) The descriptor of the socket for which information is to be retrieved. 


level 


(Input) Value indicating whether the request applies to the socket itself or to the underlying 
protocol being used. Supported values are: 


IPPROTO_IP Request applies to IP protocol layer. 
IPPROTO_TCP Request applies to TCP protocol layer. 
SOL_SOCKET Request applies to socket layer. 


2IPPROTO_IPV6 Request applies to IPv6 protocol layer. 


IPPROTO_ICMPV6 Request applies to ICMPv6 protocol layer. *& 


option_name 


(Input) The option name for which information is to be retrieved. The following tables list the 
options supported, and for which level the option applies. Assume that the option is supported for 
all address families unless the option is described otherwise. 


Note: Options directed to a specific protocol level are only supported by that protocol. An option 
that is directed to level SOL_SOCKET usually completes successfully. If the underlying protocol 
does not provide support for the option, the socket library retrieves one of the following: 


oO The default value for the option. 


oO. The value previously set with a setsockopt(). 


This provides compatibility with Berkeley Software Distributions implementations that also 
shield the application from protocols that do not support an option. 


Socket Options That Apply to the IP Layer (IPPROTO_IP) 


Option Description 


IP_OPTIONS 


Determine what options are set in the IP header. This is only 
supported for sockets with an address family of AF_INET. 


IP_TOS Get Type Of Service (TOS) and Precedence in the IP header. This 
option is only supported for sockets with an address family of 


AF_INET. 


IP_TTL Get Time To Live (TTL) in the IP header. This option is only 


supported for sockets with an address family of AF_INET. 
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IP_MULTICAST_IF Get interface over which outgoing multicast datagrams will be sent. 
An option_value parameter of type in_addr is used to retrieve the 
local IP address that is associated with the interface over which 
outgoing multicast datagrams will be sent. This option is only 
supported for sockets with an address family of AF_INET and type 
of SOCK_DGRAM or SOCK_RAW. 


IP_MULTICAST_TTL Get Time To Live (TTL) from the IP header for outgoing multicast 
datagrams. An option_value parameter of type char is used into 
which a value between 0 and 255 is retrieved. This option is only 
supported for sockets with an address family of AF_INET and type 
of SOCK_DGRAM or SOCK_RAW. 


IP_DONTFRAG Return the current Don't fragment flag setting in the IP header. A 
value of 0 indicates that it is reset. A value of 1 indicates that it is 
set. This option is supported for sockets with an address family of 
AF_INET and type of SOCK_DGRAM or SOCK_RAW only. 


IP_MULTICAST_LOOP | Determine the multicast looping mode. A non-zero value indicates 
that multicast datagrams sent by this system should also be 
delivered to this system as long as it is a member of the multicast 
group. If this option is not set, a copy of the datagram will not be 
delivered to the sending host. An option_value parameter of type 
char is used to retrieve the current setting. This option is only 
supported for sockets with an address family of AF_INET and type 
of SOCK_DGRAM or SOCK_RAW. 


IP_RECVLCLIFADDR _ | Determine if the local interface that a datagram was received will 
be returned. A value of | indicates the first 4 bytes of the reserved 
field of the sockaddr structure will contain the local interface. This 
option is only supported for sockets with an address family of 
AF_INET and type of SOCK_DGRAM. 


Socket Options That Apply to the TCP Layer (IPPROTO_TCP) 


| Option Description 


TCP_NODELAY | Determine if TCP is buffering data. This option is only supported for 


sockets with an address family of AF_INET#* or AF_INET6*Kand type 
TCP_MAXSEG 


SOCK_STREAM. 
Socket Options That Apply to the Socket Layer (SOL_SOCKET ) 


| Option Description 


Determine TCP maximum segment size. This option is only supported for 
sockets with an address family of AF_INET#* or AF_INET6* and type 
SOCK_STREAM. 


%*SO_ACCEPTCONN | Reports whether socket listening is enabled. This option stores an int 
value. This is a boolean option. 


| 


SO_BROADCAST Determine if messages can be sent to the broadcast address. This 
option is only supported for sockets with an address family of 
AF_INET and type SOCK_DGRAM or SOCK_RAW. The broadcast 
address can be determined by issuing an ioctl() specifying the 


SIOCGIFBRDADDR request. 


SO_DEBUG Determine if low level-debugging is active. 


SO_DONTROUTE Determine if the normal routing mechanism is being bypassed. This 
option is only supported by sockets with an address family of 
AF_INET 4 or AF_INET6%S. 


SO_ERROR Return any pending errors in the socket. The value returned 
corresponds to the standard error codes defined in <errno.h> 


SO_KEEPALIVE 


: 


: 


Determine if the connection is being kept up by periodic 
transmissions. This option is only supported for sockets with an 
address family of AF_INET 2% or AF_INET6 *& and type 
SOCK_STREAM. 

SO_LINGER Determine whether the system attempts to deliver any buffered data 
or if the system discards it when a close() is issued. 


For sockets that are using a connection-oriented transport service with 
an address family of AF_INET = or AF_INET6 %, the default is off 
(which means that the system attempts to send any queued data, with 
an infinite wait-time). 


For sockets that are using a connection-oriented transport service with 
an address family of AF_TELEPHONY, the default is on with a 
linger time of 1 second (which means that the system will wait up to 

1 second to send buffered data before clearing the telephone 
connection). 


SO_OOBINLINE Determine if out-of-band data is received inline with normal data. 
This option is only supported for sockets with an address family of 
AF_INET 3 or AF_INET6%. 


| SO_RCVBUF Determine the size of the receive buffer. 


SO_RCVLOWAT 


Determine the size of the receive low-water mark. This option is only 
supported for sockets with a type of SOCK_STREAM. 


#*SO_RCVTIMEO Determine the receive timeout value. This option is not supported 


unless _XOPEN_SOURCE is defined to be 520 or greater. 


i 


SO_REUSEADDR Determine if the local socket address can be reused. This option is 
supported by sockets with an address family of AF_INET#* or 


AF_INET6% and a type of SOCK_STREAM or SOCK_DGRAM. 


| SO_SNDBUF Determine the size of the send buffer. 


SO_SNDLOWAT Determine the size of the send low-water mark. This option is not 
supported. 
2*SO_SNDTIMEO Determine the send timeout value. This option is not supported unless 
_XOPEN_SOURCE is defined to be 520 or greater. 


|SOTYPE TYPE Determine | Determine the value for the socket ype. value for the socket | Determine the value for the socket ype. 


sore __ Determine if the loopback feature is being used. This option is not 
supported. 


2» Socket Options That Apply to the IPv6 Layer IPPROTO_IPV6) 


| Option Description 


IPV6_UNICAST_HOPS Get the hop limit value that will be used for subsequent unicast 
packets sent by this socket. An option_value parameter of type 
int is used to retrieve the current setting. This option is only 
supported for sockets with an address family of AF_INET6. 


IPV6_MULTICAST_IF Get the interface over which outgoing multicast datagrams will 
be sent. An option_value parameter of type unsigned int is used 
to retrieve the interface index that is associated with the 
interface over which outgoing multicast datagrams will be sent. 
This option currently is not supported. 


IPV6_MULTICAST_HOPS | Get the hop limit value that will be used for subsequent 
multicast packets sent by this socket. An option_value 
parameter of type int is used to retrieve the current setting. This 
option currently is not supported. 


IPV6_MULTICAST_LOOP | Determine the multicast looping mode. A value of 1 (default), 
indicates that multicast datagrams sent by this system should 
also be delivered to this system as long as it is a member of the 
multicast group. If this option is 0, a copy of the datagram will 
not be delivered to the sending host. An option_value parameter 
of type unsigned int is used to retrieve the current setting. This 
option is currently not supported. 


IPV6_V6ONLY Determine the AF_INET6 communication restrictions. A 
non-zero value indicates that this AF_INET®6 socket is restricted 
to IPv6 communications only. This option stores an int value. 
This is a boolean option. By default this option is turned off. 
This option is only supported for sockets with an address family 
of AF_INET®. 


IPV6_CHECKSUM Determine if the kernel will calculate and insert a checksum for 
output and verify the received checksum on input, discarding 
the packet if the checksum is in error for this socket. An 
option_value parameter of type int is used to retrieve the current 
setting. If this option is -1 (the default), this socket option is 
disabled. A value of 0 or greater specifies an integer offset into 


the user data of where the checksum is located. This option is 
only supported for sockets with an address family of AF_INET6 
and type of SOCK_RAW with a protocol other than 
IPPROTO_ICMPV6. The checksum is automatically computed 
for protocol IPPROTO_ICMPV6. 


Socket Options That Apply to the ICMPv6 Layer IPPROTO_ICMPV6) 


| Option | Description 


ICMP6_FILTER |} Determine the current ICMPv6 Type Filtering. An option_value parameter 
of type struct icmp6_filter, defined in <netinet/icmp6.h> is used to 
retrieve the current setting. The following macros, defined in 
<netinet/icmp6.h> can be used after retrieval of the type filtering structure 
to determine whether or not specific ICMPv6 message types will be passed 


to the application or be blocked: ICMP6_FILTER_WILLPASS and 
ICMP6_FILTER_WILLBLOCK. This option is only supported for sockets 
with an address family of AF_INET6 and type of SOCK_RAW witha 
protocol of IPPROTO_ICMPV6. 
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option_value 


(Output) A pointer to the option value. Integer flags/values are returned by getsockopt() for all the 
socket options except for SO_LINGER , IP_OPTIONS , IP_MULTICAST_IF , 
IP_MULTICAST_TTL, IP_MULTICAST_LOOP, and 3 ICMP6_FILTER*S. 


The following options should be considered as set if a nonzero value for the option_value 
parameter is returned: 

#SO_ACCEPTCONN*& 

o SO_BROADCAST 
o SO_DEBUG 

o SO_DONTROUTE 
o SO_KEEPALIVE 
o SO_OOBINLINE 
o SO_REUSEADDR 
O 
O 
O 
O 
O 


O 


SO_USELOOPBACK 
TCP_NODELAY 
IP_MULTICAST_LOOP 
IP_DONTFRAG 
#IPV6_V6ONLY 


o IPV6_MULTICAST_IF 
o IPV6_MULTICAST_LOOP*& 


For the SO_LINGER option, option_value is a pointer to where the structure linger is stored. The 
structure linger is defined in <sys/socket.h>. 


struct linger { 
int l_onoff; 
int 1_linger; 


by 


The l_onoff field determines if the linger option is set. A nonzero value indicates the linger option 
is set and is using the /_linger value. A zero value indicates that the option is not set. The /_linger 
field is the time to wait before any buffered data to be sent is discarded. The following occur on a 
close(): 


o For AF_INET#* and AF_INET6*& sockets: 


m If the /_onoff value is zero, the system attempts to send any buffered data with an 
infinite wait-time. 


m If the /_onoff value is nonzero and the /_linger value is nonzero, the system 
attempts to send any buffered data for /_linger time. If l_linger time has elapsed 
and the data is still not successfully sent, it is discarded. When data is discarded, 
the remote program may receive a [ECONNRESET]. 


o For AF_INET sockets over SNA: 


m If the /_onoff value is nonzero and the /_linger value is zero, the system waits 
indefinitely (no timer is implemented). Otherwise, if the /_onoff value is nonzero 
and the /_linger value is zero, the system discards any buffered data. When data is 
discarded, the remote program may receive a [ECONNRESET]. 


o For AF_TELEPHONY sockets: 


m If the /_onoff value is zero, the system will wait until all buffered data is sent or 1 
second has elapsed, whichever occurs first, before clearing the telephone 
connection (that is, hanging up). 


m If the /_onoff value is nonzero, the system will wait until all buffered data is sent or 
L_ linger seconds have elapsed, whichever occurs first, before clearing the 
telephone connection (that is, hanging up). 


Note: An application must implement an application level confirmation. Guaranteed receipt of data 
by the partner program is required. Setting SO_LINGER does not guarantee delivery. 


=» For the SO_RCVTIME and SO_SNDTIME options, option_value is a pointer to where the 
structure timeval is stored. The structure timeval is defined in <sys/time.h>. 


struct timeval { 


long tv_sec; 
long tv_usec; 


ae 


% 


For the IP_LOPTIONS option, option_value is a pointer to storage in which data representing the IP 
options (as specified in RFC 791) is stored. getsockopt() returns the options in the following 
format: 


| IP address | IP options | ... | IP options 


IP address is a 4-byte IP address, and IP options identifies the IP options that were set using 
setsockopt(). If an IP option set using setsockopt() contained a source routing option (strict or 
loose), the first IP address in the source routing option list is removed. The IP options are adjusted 
accordingly. (For this adjustment, the length in the IP options portion is changed, and alignment is 
kept by adding no-operation option). The buffer is returned in the same format. The first 4 bytes are 
the IP address that was removed, and this is followed by the remaining IP options, if any. If the IP 
options portion does not contain a source routing option, the first 4 bytes are set to zero. 


For the IP_MULTICAST_IF option, option_value is a pointer to storage in which the structure 
in_addr, defined in <netinet/in.h> as the following, will be stored: 


struct in_addr { 
u_long s_addr; /* IP address */ 
}; 


The s_addr field that is returned will be the local IP address that is associated with the interface 
over which outgoing multicast datagrams are being sent. 


Notes: 


1. For sockets that use a connection-oriented transport service, IP options that are set using 
setsockopt() are only used if they are set prior to a connect() being issued. After the 
connection is established, any IP options that the user sets are ignored. 


2. If the IP options portion contains a source routing option, then the address in the source 
routing option overrides the destination address. The destination address may have been 
specified on an output operation (for example, on a sendto()) or on a connect(). 


3. If a socket has a type of SOCK_RAW and a protocol of IPPROTO_RAW, any IP options 
set using setsockopt() are ignored (since the user must supply the IP header data on an 
output operation as part of the data that is being transmitted). 


4. The structure ip_opts (defined in <netinet/in.h>) can be used to receive IP options. 


option_length 


(I/O) The length of the option_value. The option_length parameter must be initially set by the 
caller. option_length is changed on return to indicate the actual amount of storage used. 


Note: For option values that are of type integer, the length of the option_value pointed to by the 
option_length parameter must be set to a value that is greater or equal to the size of an integer. If 
the length is not set correctly, a correct option value is not received. 


Authorities 


No authorization is required. 


Return Value 


getsockopt() returns an integer. Possible values are: 


e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When getsockopt() fails, errno can be set to one of the following: 


[EBADF] 


Descriptor not valid. 


[ECONNABORTED] Connection ended abnormally. 


[EFAULT] 


[EINVAL] 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent on 
the socket. 


e A protocol error was detected. 


Bad address. 


The system detected an address which was not valid while attempting to access 
the option_value or option_length parameters. 


Parameter not valid. 


This error code indicates one of the following: 


e The level parameter specifies a level that is not supported. (except for 
when the socket has an address family of AF_UNIX, in which case 
[ENOPROTOOPT] is returned). 


e The option_name parameter specifies a value that is not valid (except for 
when the level is SOL_SOCKET , in which case [ENOPROTOOPT] is 
returned). 


e The option_length parameter points to an integer that has a negative 
value. 


[EIO] Input/output error. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOPROTOOPT] _ The protocol does not support the specified option. 


This error code indicates one of the following: 


e The socket has an address family of AF_UNIX and the /evel parameter 
specified is not SOL_SOCKET . 


e The level parameter specifies a level of SOL_SOCKET and the 
option_name parameter specifies a value that is not valid. 


[ENOTCONN] Requested operation requires a connection. 


This error code is only returned if the /evel parameter specifies a level other than 
SOL_SOCKET and the socket_descriptor parameter points to a socket that is 
using a connection-oriented transport service that has had its connection broken. 


[ENOTSOCK] The specified descriptor does not reference a socket. 


[EPERM] Operation not permitted. 


The executing user profile must have *IOSYSCFG special authority to get 
options when the /evel parameter specifies [PPROTO_IP and the option_value 
parameter is IP_OPTIONS . 


[EUNKNOWN] Unknown system state. 
[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. Socket options are defined in <sys/socket.h>, IP options are defined in <netinet/ip.h> and 
<netinet/in.h>, TCP options are defined in <netinet/tcp.h>, 2+IPv6 and ICMPv6 options are 
defined in <netinet/in.h>*& 


2. The user profile for a running application must have the *LOSYSCFG special authority to specify 
the /evel parameter as IPPROTO_IP and the option_value parameter as IP_OPTIONS . 


3. When a TCP connection is closed for a socket using the AF_INET 2 or AF_INET6 & address 
families, the port associated with that connection is not made available until twice the Maximum 
Segment Life (MSL) time in seconds has passed. The MSL time is approximately 2 minutes. The 
SO_REUSEADDR option allows a bind() to succeed when requesting a port that is being held 
during this time frame. This can be especially useful if a server is abruptly ended and restarted. 


Notes: 


1. For AF_INET 3 and AF_INET6, “SOCK_STREAM sockets, this option does not allow 
two servers to successfully issue a bind() requesting the same port number and local 
address combination. For AF_INET #* and AF_INET6, “SOCK_DGRAM sockets, the 
SO_REUSEADDR option does allow multiple servers to successfully bind to the same 
port. When broadcast or multicast datagrams are received for a given port, each server that 
is bound to that port receives a copy of the datagram provided each server has enabled the 
SO_REUSEADDR option. 


2. This option does not affect unicast datagram delivery. 


4. Issuing a getsockopt() with the SO_ERROR option results in the resetting of the SOLERROR 
option to zero. Issuing another getsockopt() with the SO_ERROR option also returns a value of 
zero, assuming no errors occur on the socket. Other functions, when issued, also reset the 
SO_ERROR option to zero. These functions are: 


o read(), readv(), recv(), recvmsg(), recvfrom() 
Oo connect() (only when using a connectionless transport service) 
5. #*When you develop in C-based languages and an application is compiled with the 


_XOPEN_SOURCE macro defined to the value 520 or greater, the getsockopt() API is mapped to 
qso_getsockopt98().%& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®® 


e setsockopt()--Set Socket Options 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


givedescriptor()--Pass Descriptor Access to 
Another Job 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int givedescriptor(int descriptor, 
char *target_job) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The givedescriptor() function is used to pass a descriptor from one OS/400 job to another OS/400 job. 


Parameters 


descriptor 
(Input) The descriptor that is to be passed to the target job. 


target_job 


(Input) A pointer to the internal job identifier of the target job that is to receive the descriptor 
referenced by the descriptor parameter. 


Authorities 


To give a descriptor, the source thread must be running under one of the following user profiles: 
e A user profile that is the same as the job user identity of the target job 
e A user profile that has all object (*ALLOBJ) special authority 


The job user identity is the name of the user profile by which a job is known to other jobs. It is described 


in more detail in the Work Mana ement book on the V5R1 Supplemental Manuals Web site. 


Return Value 


givedescriptor() returns an integer. Possible values are: 


e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When givedescriptor() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 
The job does not have the appropriate privileges required to give the descriptor. 


[EBADF] Descriptor not valid. 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
target_job parameter. 


[EINVAL] Parameter not valid. 
This error code indicates one of the following: 
e The target_job parameter points to data that is not valid. 
e The target_job parameter refers to a job that is not active. 


[EIO] Input/output error. 


[EOPNOTSUPP] Operation not supported. 


The underlying instance represented by the descriptor does not support passing 
access rights. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. The information to specify in the target_job parameter can be obtained in the actual target job by 
using a work management API (for example, QUSRJOBD to retrieve the internal job identifier. 


It is the responsibility of the application programmer to privately pass this information from the 
target job to the job that issues the givedescriptor(). One possible method that could be used to 
exchange this information is to use data queues. 


2. The target_job does not have to be waiting on a takedescriptor() for the givedescriptor() to 
complete successfully. 


3. If both the job in which the givedescriptor() is issued and the target_job end while a descriptor is in 
transit, the descriptor is reclaimed by the system, and the resource that it represents is closed. 


4. For files and directories, givedescriptor() is only supported for objects in the root and QOpenSys 
file systems. 


Related Information 


e takedescriptor(Q--Receive Socket Access from Another Job 


e sendmsg()--Send Data or Descriptors or Both 


e@ recvmsg()--Receive Data or Descriptors or Both 


@ spawn()--Spawn Process 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


ioctl()--Perform I/O Control Request 


Syntax 


#include <sys/types.h> 
#include <sys/ioctl.h> 


int ioctl(int descriptor, 
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unsigned long request, 


Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The ioctl() function performs control functions (requests) on a descriptor. 


Parameters 


descriptor 


(Input) The descriptor on which the control request is to be performed. 


request 


(Input) The request that is to be performed on the descriptor. 


(Input) A variable number of optional parameters that are dependent on the request. 


The ioctl() requests that are supported are: 


FIOASYNC 


FIOCCSID 


Set or clear the flag that allows the receipt of asynchronous I/O signals (SIGIO). 


The third parameter represents a pointer to an integer flag. A nonzero value sets the socket to generate 
SIGIO signals, while a zero value sets the socket to not generate SIGIO signals. Note that before the 
SIGIO signals can be delivered, you must use either the FFOSETOWN or SIOCSPGRP ioctl() request, or 
the F_LSETOWN fcntl() command to set a process ID or a process group ID to indicate what process or 
group of processes will receive the signal. Once conditioned to send SIGIO signals, a socket will generate 
SIGIO signals whenever certain significant conditions change on the socket. For example, SIGIO will be 
generated when normal data arrives on the socket, when out-of-band data arrives on the socket (in 
addition to the SIGURG signal), when an error occurs on the socket, or when end-of-file is received on 
the socket. It is also generated when a connection request is received on the socket (if it is a socket on 
which the listen() verb has been done). Also note that a socket can be set to generate the SIGIO signal by 
using the fentl() command F_SETFL with a flag value specifying FASYNC. 


Return the coded character set ID (CCSID) associated with the open instance represented by the 
descriptor and the CCSID associated with the object. The third parameter represents a pointer to the 
structure QpOIFIOCCSID, which is defined in <sys/ioctl.h>. This information may be necessary to 
correctly manipulate data read from or written to a file opened in another process. 


If the open instance represented by the descriptor is in binary mode (the open() did not specify the 
O_TEXTDATA open flag), the open instance CCSID returned is equal to the object CCSID returned. 


FIOGETOWN 


FIONBIO 


FIONREAD 


FIOSETOWN 


SIOCADDRT 


Get the process ID or process group ID that is to receive the SIGIO and SIGURG signals. 


The third parameter represents a pointer to a signed integer that will contain the process ID or the process 
group ID to which the socket is currently sending asynchronous signals such as SIGURG. A process ID is 
returned as a positive integer, and a process group ID is specified as a negative integer. A 0 value returned 
indicates that no asynchronous signals can be generated by the socket. A positive or a negative value 
indicates that the socket has been set to generate SIGURG signals. 


Set or clear the nonblocking I/O flag (O_NONBLOCK oflag). The third parameter represents a pointer to 
an integer flag. A nonzero value sets the nonblocking I/O flag for the descriptor; a zero value clears the 
flag. 


Return the number of bytes available to be read. The third parameter represents a pointer to an integer that 
is set to the number of bytes available to be read. 


Set the process ID or process group ID that is to receive the SIGIO and SIGURG signals. 


The third parameter represents a pointer to a signed integer that contains the process ID or the process 
group ID to which the socket should send asynchronous signals such as SIGURG. A process ID is 
specified as a positive integer, and a process group ID is specified as a negative integer. Specifying a 0 
value resets the socket such that no asynchronous signals are delivered. Specifying a process ID or a 
process group ID requests that sockets begin sending the SIGURG signal to the specified ID when 
out-of-band data arrives on the socket. 


Add an entry to the interface routing table. Valid for sockets with address family of AF_INET. 


The third parameter represents a pointer to the structure rtentry, which is defined in <net/route.h>: 


struct rtentry [ 
struct sockaddr rt_dst; 
struct sockaddr rt_mask; 
struct sockaddr rt_gateway; 
int rt_mtu; 
u_short rt_flags; 
u_short rt_refcnt; 
u_char rt_protocol; 
u_char rt_TOS; 
char rt_if [IFNAMSIZ]; 

li 


The rt_dst, rt_mask, and rt_gateway fields are the route destination address, route address mask, and 
gateway address, respectively. rt_mtu is the maximum transfer unit associated with the route. rt_flags 
contains flags that give some information about a route (for example, whether the route was created 
dynamically, whether the route is usable, type of route, and so on). rt_refcnt indicates the number of 
references that exist to the route entry. rt_protocol indicates how the route entry was generated (for 
example, configuration, ICMP redirect, and so on). rt_tos is the type of service associated with the route. 
rt_if is a NULL-terminated string that represents the interface IP address in dotted decimal format that is 
associated with the route. 


To add a route, the following fields must be set: 
e@ rt_dst 

rt_mask 

rt_gateway 

rt_tos 


rt_protocol 


rt_mtu (Setting the rt_mtu value to zero essentially means use the MTU from the associated line 
description used when the route is bound to an IFC.) 


e rt_if (rt_ifcan be set to the dotted decimal equivalent of INADDR_ANY, which is 0.) 


In addition, the rt_flags bit flags can be set to the following: 


e RTF_NOREBIND_IFC_FAIL if no rebinding of the route is to occur when the interface 
associated with the route fails. 


e RTF_NOREBIND_IFC_ACTV if no rebinding is to occur when interfaces are activated or 


SIOCATMARK 


SIOCDELRT 


SIOCGIFADDR 


SIOCGIFBRDADDR 


deactivated. 


To delete a route, the following fields must be set: 
e rt_dst 
@ rt_mask 
e@ rt_gateway 
e rt_tos 


e rt_protocol 
All other fields are ignored when adding or removing an entry. 
Return the value indicating whether socket's read pointer is currently at the out-of-band mark. 


The third parameter represents a pointer to an integer flag. If the socket's read pointer is currently at the 
out-of-band mark, the flag is set to a nonzero value. If it is not, the flag is set to zero. 


Delete an entry from the interface routing table. Valid for sockets with address family of AF_INET. 
See SIOCADDRT for more information on the third parameter. 
Get the interface address. Valid for sockets with address family of AF_INET. 


The third parameter represents a pointer to the structure ifreq, defined in <net/if.h>: 


struct ifreq { 

char ifr_name[IFNAMSIZE]; 

union { 

struct sockaddr ifru_addr; 
struct sockaddr ifru_mask; 
struct sockaddr ifru_broadaddr; 
short ifru_flags; 

int ifru_mtu; 

int infu_rbufsize; 

char ifru_linename[10]; 
char ifru_TOS; 

} ifr_ifru; 


}; 


ifr_name is the name of the interface for which information is to be retrieved. The OS/400 
implementation requires this field to be set to a NULL-terminated string that represents the interface IP 
address in dotted decimal format. Depending on the request, one of the fields in the ifr_ifru union will be 
set upon return from the ioctl() call. ifru_addr is the local IP address of the interface. ifru_mask is the 
subnetwork mask associated with the interface. ifru_broadadadr is the broadcast address. ifru_flags 
contains flags that give some information about an interface (for example, token-ring routing support, 
whether interface is active, broadcast address, and so on). ifru_mtu is the maximum transfer unit 
configured for the interface. ifru_rbufsize is the reassembly buffer size of the interface. ifru_linename is 
the line name associated with the interface. ifru_TOS is the type of service configured for the interface. 


Get the interface broadcast address. Valid for sockets with address family of AF_INET. 


See SIOCGIFADDR for more information on the third parameter. 


SIOCGIFCONF Get the interface configuration list. Valid for sockets with address family of AF_INET. 


The third parameter represents a pointer to the structure ifconf, defined in <net/if.h>: 


struct ifconf [ 
int ifc_len; 
int ifc_configured; 
int ifc_returned; 
union { 
caddr_t ifcu_buf; 
struct ifreq *ifcu_req; 
} ifc_ifcu,; 
li 
ifc_len is a value-result field. The caller passes the size of the buffer pointed to by ifcu_buf. On return, 
ifc_len contains the amount of storage that was used in the buffer pointed to by ifcu_buf for the interface 
entries. ifc_configured is the number of interface entries in the interface list. ifc_returned is the number of 
interface entries that were returned (this is dependent on the size of the buffer pointed to by ifcu_buf). 
ifcu_buf is the user buffer in which a list of interface entries will be stored. Each stored entry will be an 
ifreq structure. 


To get the interface configuration list, the following fields must be set: 
e ifc_len 
e@ ifcu_buf 


See SIOCGIFADDR for more information on the list of ifreqg structures returned. For this request, the 
ifr_name and ifru_adadr fields will be set to a value. 


Note: Additional information about each individual interface can be obtained using these values and the 
other interface-related requests. 


SIOCGIFFLAGS Get interface flags. Valid for sockets with address family of AF_INET. 
See SIOCGIFADDR for more information on the third parameter. 

SIOCGIFLIND Get the interface line description name. Valid for sockets with address family of AF_INET. 
See SIOCGIFADDR for more information on the third parameter. 

SIOCGIFMTU Get the interface network MTU. Valid for sockets with address family of AF_INET. 
See SIOCGIFADDR for more information on the third parameter. 


SIOCGIFNETMASK _ Get the mask for the network portion of the interface address. Valid for sockets with address family of 
AF_INET. 


See SIOCGIFADDR for more information on the third parameter. 

SIOCGIFRBUFS Get the interface reassembly buffer size. Valid for sockets with address family of AF_INET. 
See SIOCGIFADDR for more information on the third parameter. 

SIOCGIFTOS Get the interface type-of-service (TOS). Valid for sockets with address family of AF_INET. 
See SIOCGIFADDR for more information on the third parameter. 

SIOCGPGRP Get the process ID or process group ID that is to receive the SIGIO and SIGURG signals. 


See FIOGETOWN for more information on the third parameter. 


SIOCGRTCONF Get the route configuration list. Valid for sockets with address family of AF_INET. 


For the SIOCGRTCOMF request, the third parameter represents a pointer to the structure rtconf, also 
defined in <net/route.h>: 


struct rtconf [ 
int rtc_len; 
int rtc_configured; 
int rtc_returned; 
union { 
caddr_t rtcu_buf; 
struct rtentry *rtcu_req; 
} Lec rtcu; 


]; 


rtc_len is a value-result field. The caller passes the size of the buffer pointed to by rtcu_buf. On return, 
rtc_len contains the amount of storage that was used in the buffer pointed to by rtcu_buf for the route 
entries. rtc_configured is the number of route entries in the route list. rtc_returned is the number of route 
entries that were returned (this is dependent on the size of the buffer pointed to by rtcu_buf). rtcu_buf is 
the user buffer in which a list of route entries will be stored. Each stored entry will be an rtentry structure. 


To get the route configuration list, the following fields must be set: 
e rtc_len 


e@ rtcu_buf 


See SIOCADDRT for more information on the list of rtentry structures returned. For this request, all 
fields in each rtentry structure will be set to a value. 


SIOCSENDQ Return the number of bytes on the send queue that have not been acknowledged by the remote system. 
Valid for sockets with address family of AF_INET #or AF_INET6& and socket type of 
SOCK_STREAM. 


The third parameter represents a pointer to an integer that is set to the number of bytes yet to be 
acknowledged as being received by the remote TCP transport driver. 


Notes: 


1. SIOCSENDQ is used after a series of blocking or non-blocking send operations to see if the sent 
data has reached the transport layer on the remote system. Note that this does not not guarantee 
the data has reached the remote application. 


2. When SIOCSENDQ is used in a multithreaded application, the actions of other threads must be 
considered by the application. SIOCSENDQ provides a result for a socket descriptor at the given 
point in time when the ioctl()) request is received by the TCP transport layer. Blocking send 
operations that have not completed, as well as non-blocking send operations in other threads 
issued after the SIOCSENDQ ioctl(), are not reflected in the result obtained for the SIOCSENDQ 
ioctl). 


3. Ina situation where the application has multiple threads sending data on the same socket 
descriptor, the application should not assume that all data has been received by the remote side 
when 0 is returned if the application is not positive that all send operations in the other threads 
were complete at the time the SIOCSENDQ ioctl() was issued. An application should issue the 
SIOCSENDQ ioctl() only after it has completed all of the send operations. No value is added by 
querying the machine to see if it has sent all of the data when the application itself has not sent all 
of the data in a given unit of work. 


SIOCSPGRP Set the process ID or process group ID that is to receive the SIGIO and SIGURG signals. 


See FIOSETOWN for more information on the third parameter. 


SIOCSTELRSC Set telephony resources. Valid for sockets with address family of AF_TELEPHONY. 


The third parameter represents a pointer to a TelResource structure, which is defined in <nettel/tel.h>. 


struct TelResource { /* telephony resource structure */ 
int trCount; /* number of devices nA 
char trReserved[12]; /* reserved *y 

void* trResourceList; /* pointer to array of system 
pointers */ 


}; 


trCount] is the number of devices that are to be associated with the socket, trReserved is a reserved field, 
and trResourceList is a pointer to an array of space pointers. Each of these space pointers is the address of 
a device that will be associated with the socket. 

Notes: 


1. This request will associate one or more telephony (*TEL) network devices with a socket. Once 
the association is made, it will last until the socket is closed. 


2. The user is responsible for resolving each device name to a system pointer. 


3. Before the device can be associated with a socket, the following conditions must be met: 
oO The PPP line, network controller, and network device descriptions must exist. 
oO The PPP line must be associated with an ISDN network controller. 


oO The PPP line must be associated with a connection list and connection list entry (inbound 
or outbound, as appropriate). 


o The line, controller, and device must be varied on. 


4. The user must have at least operational authority for the devices to be associated with the socket. 
5. A device cannot be associated with more than one socket at a time. 


6. If the SIOCSTELRSC request fails for any reason, none of the specified devices will be 
associated the socket. 


7. For more information about this request and the AF_TELEPHONY address family, please see 
Socket address family. 


Authorities 


No authorization is required. 


Return Value 


ioctl() returns an integer. Possible values are: 
e@ O(ioctl() was successful) 


e -/ (ioctl() was not successful. The errno global variable is set to indicate the error.) 


Error Conditions 


If ioctl() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error 
other than those listed here. 


[EACCES] 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBUSY] 


[EDAMAGE] 


[EFAULT] 


/[EINTR] 


[EINVAL] 


[EIO] 


[ENOBUFS] 


[ENOSPC] 


Permission denied. 

An attempt was made to access an object in a way forbidden by its object access permissions. 

The thread does not have access to the specified file, directory, component, or path. 

If you are accessing a remote file through the Network File System, update operations to file permissions at the 
server are not reflected at the client until updates to data that is stored locally by the Network File System take 
place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between 
refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs 


(UID) or group IDs (GID) on the local and remote systems. 


Operation would have caused the process to be suspended. 


Descriptor not valid. 


A descriptor argument was out of range, referred to an object that was not open, or a read or write request was 
made to an object that is not open for that operation. 


A given descriptor or directory pointer is not valid for this operation. The specified descriptor is incorrect, or 
does not refer to an open object. 


A file ID could not be assigned when linking an object to a directory. 

The file ID table is missing or damaged. 

To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible. 

Resource busy. 

An attempt was made to use a system resource that is not available at this time. 

A damaged object was encountered. 

A referenced object is damaged. The object cannot be used. 

The address used for an argument is not correct. 

While attempting to access a parameter passed to this function, the system detected an address that is not valid. 


Interrupted function call.& 


The value specified for an argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on an object and the operation 
specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. Either the requested function is not supported, or the 
optional parameter is not valid. 


Input/output error. 
A physical I/O error occurred. 
A referenced object may be damaged. 


There is not enough buffer space for the requested operation. 


No space available. 


The requested operations required additional space on the device and there is no space left. This could also be 
caused by exceeding the user profile storage limit when creating or transferring ownership of an object. 


Insufficient space remains to hold the intended object. 


[ENOSYS] Function not implemented. 


An attempt was made to use a function that is not available in this implementation for any object or any 
arguments. 


The path name given refers to an object that does not support this function. 

[ENOTAVAIL] Independent Auxiliary Storage Pool (ASP) is not available. 
The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage (RCLSTG) processing. 
To recover from this error, wait until processing has completed for the independent ASP. 


[ENOTSAFE] Function is not allowed in a job that is running with multiple threads. 


[EPERM] Operation not permitted. 
You must have appropriate privileges or be the owner of the object or other resource to do the requested 
operation. 

[EPIPE] Broken pipe. 


[ERESTART] A system call was interrupted and may be restarted. 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have been deleted at the 
server. 


[EUNATCH] The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] Unknown system state. 


The operation failed because of an unknown system state. See any messages in the job log and correct any 
errors that are indicated, then retry the operation. 


If interaction with a file server is required to access the object, errno could also indicate one of the following errors: 


[EADDRNOTAVAIL] Address not available. 

[ECONNABORTED] Connection ended abnormally. 

[ECONNREFUSED] The destination socket refused an attempted connect operation. 
[ECONNRESET] A connection with a remote socket was reset by that socket. 
[EHOSTDOWN] A remote host is not available. 

[EHOSTUNREACH] A route to the remote host is not available. 

[ENETDOWN] The network is not currently available. 

[ENETRESET] A socket is connected to a host that is no longer available. 
[ENETUNREACH] — Cannot reach the destination network. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPFA0D4 E File system error occurred. Error number &1. 
CPFA081 E Unable to set return value or error code. 
CPF3CF2 E Error(s) occurred during running of &1 API. 
CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 


oO Where multiple threads exist in the job. 


O The object on which this function is operating resides in a file system that is not threadsafe. Only the following file 
systems are threadsafe for this function: 


m Root 

mw QOpenSys 

m User-defined 

mg QNTC 

mw QSYS.LIB 

m Independent ASP QSYS.LIB & 
m QOPT 


2. QDLS File System Differences 


QDLS does not support ioctl(). 
3. QOPT File System Differences 


QOPT does not support ioctl(). 


4. A program must have the appropriate privilege *IOSYSCFG to issue any of the following requests: SIOCADDRT and 
SIOCDELRT. 


Related Information 


e The <sys/ioctl.h> file (see Header Files for UNIX-Type Functions) 


e@ The <sys/types.h> file (see Header Files for UNIX-Type Functions) 


e fcntlQ--Perform File Control Command 


e@ Socket Programming 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


listen()--Invite Incoming Connections Requests 


Syntax 


#include <sys/socket.h> 


int listen(int socket_descriptor, 
int back_log) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The listen() function is used to indicate a willingness to accept incoming connection requests. If a listen() is 
not done, incoming connections are silently discarded. 


Parameters 


socket_descriptor 


(Input) The descriptor of the socket that is to be prepared to receive incoming connection requests. 
back_log 

(Input) The maximum number of connection requests that can be queued before the system starts 

rejecting incoming requests. The maximum number of connection requests that can be queued is 

defined by {SOMAXCONN} (defined in <sys/socket.h>). 


Authorities 


No authorization is required. 


Return Value 


listen() returns an integer. Possible values are: 


e@ -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When listen() fails, errno can be set to one of the following: 


[EADDRNOTAVAIL] Address not available. 


[EBADF] 


[EINVAL] 


[EIO] 


[ENOBUFS] 


[ENOTSOCK] 


[EOPNOTSUPP] 


[EUNKNOWN] 


[EUNATCH] 


Error Messages 


The socket has an address family of AF_INET #or AF_INET6%, the socket 
was not bound, and the system tried to bind the socket but could not because a 
port was not available. 


Descriptor not valid. 


Parameter not valid. 


This error code indicates one of the following: 


e A connect() has been issued on the socket pointed to by the 
socket_descriptor parameter. 


e The socket_descriptor parameter points to a socket with an address 
family of AF_UNIX that has not been bound to an address. 


Input/output error. 

There is not enough buffer space for the requested operation. 

The specified descriptor does not reference a socket. 

Operation not supported. 

The socket_descriptor parameter points to a socket that does not support listen(). 
listen() is only supported on sockets that are using a connection-oriented 
protocol (socket type of SOCK_STREAM). 


Unknown system state. 


The protocol required to support the specified address family is not available at 
this time. 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. If the socket is not bound to an address and the address family is: 


o AF_INET, the system automatically selects an address INADDR_ANY and an available 
port number) and binds it to the socket. 


o # AF_INETO6, the system automatically selects an address (in6addr_any and an available 
port number) and binds it to the socket.“ 


o AF_UNIX, the listen() fails with [EINVAL]. 


o AF_TELEPHONY, the system will bind the socket to TELADDR_ANY, which indicates 
that calls will be answered for any of the local telephone numbers for which the associated 
devices have been configured. 


2. listen() can be issued multiple times for a particular socket. 


3. If the back_log parameter specifies a value greater than the maximum {SOMAXCONN} allowed, 
the specified value will be ignored and SOMAXCONN will be used. # If the back_log parameter 
specifies a negative value, the specified value will be ignored and zero will be used. 


4. The optimal setting of the listen() back_log value is dependent on the following factors: 


oO The design of the server--how the server processes connection requests. Does it handle 
each connection request itself or does it pass the actual processing of the connection to a 
child or worker job? In other words, how long does it take for the server to handle an 
incoming connection until it can handle the next one? The shorter the time, the smaller the 
back_log value can be. 


o. The number and rate of connection requests the server can expect over a given period of 
time will help determine the back_log value. More connection requests coming in over a 
shorter period of time requires a larger back_log value. 


oO The following may determine how the server performs and thus how long it will take for an 
accept request to be serviced: 


m The system processor size 
= How storage pools used by the server are allocated 


m Machine performance 
The faster the server performance, the smaller the back_log value can be. 


Also, to help you determine how much main storage is consumed by a connection request in the 
listen() back_log, consider the following: 


o Each connection request in the backlog consumes at least 1KB of storage. 


o Each connection request can consume an additional storage amount equal to the size of 


TCP receive buffer. You can determine the TCP receive buffer size by looking at the 
TCPRCVBUF parameter value on the Change TCP Attributes (CHGTCPA) CL command. 
This storage amount will be consumed only if the remote peer (client) sends data after the 
connection is established and put into the backlog. 


5. For AF_TELEPHONY sockets, the back_log value is ignored. 


6. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the listen() API is mapped to 
qso_listen98().& 


Related Information 


e@ %_XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


@ accept()--Wait for Connection Request and Make Connection 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


QsoCreatelOCompletionPort()--Create I/O 
Completion Port 


Syntax 


#include <qsoasync.h> 
int QsoCreateIOCompletionPort () 


Service Program Name: QSOSRV3 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsoCreatel[OCompletionPort is used to create a common wait point for a completed overlapped I/O 
operation. The wait point is represented by the I/O completion port handle returned by the 
QsoCreateIOCompletionPort() function. This handle is specified on QsoStartRecv and QsoStartSend 
functions to initiate overlapped I/O operations. 


Authorities 


No authorization is required. 


Return Values 


QsoCreatelOCompletionPort() returns an integer. Possible values are: 
e -1| - Unsuccessful, errno is set to a value defined below. 


e n- Successful, where n is an I/O completion port handle that can be used in conjunction with 
overlapped I/O functions QsoStartRecv(), QsoStartSend(), and QsoPostlOCompletionPort(). 


Errno Conditions 


When QsoCreateIOCompletionPort() fails, errno can be set to one of the following: 


[ENOBUFS] The limit of 256 I/O completion ports has been exceeded for this process. 


[EUNKNOWN]_ Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. The I/O completion port handle is a process scoped resource; therefore, you may not start an 
overlapped I/O function on a socket in one process and check for its completion in another process. 


2. The number of I/O completion ports that can be active for a given process is 256. 


Related Information 


e@ QsoDestroyIOCompletionPort()--Create I/O Completion Port 


e@ QsoPostIOCompletionPort()--Post Request on I/O Completion Port 


e@ QsoStartRecv--Start Asynchronous Recv Operation 


e@ QsoStartSend--Start Asynchronous Send Operation 


e@ QsoWaitForlIOCompletionQ--Wait for I/O Completion Operation 


API Introduced: V5R1 
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QsoDestroylOCompletionPort()--Destroy I/O 
Completion Port 


Syntax 


#include <qsoasync.h> 


int QsoDestroylOCompletionPort 
(int IOCompletionPort) 


Service Program Name: QSOSRV3 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsoDestroy[OCompletionPort is used to destroy an I/O completion port. 


Parameters 
int IOCompletionPort (Input) 


The I/O completion port to be destroyed. All threads sleeping with QsoWaitForlOCompletion() on 
the I/O completion port being destroyed will be awakened with return value of -1 and errno value 
of EDESTROYED. 


Authorities 


No authorization is required. 


Return Values 


QsoDestroyIOCompletionPort() returns an integer. Possible values are: 
e 0 - Successful destruction of the I/O completion port. 


e -1 - The function has failed. Inspect the errno value to determine the cause of the failure. 


Errno Conditions 


When QsoDestroyIOCompletionPort fails, errno can be set to one of the following: 


[EINVAL] The specified I/O completion port is not valid. 


[EUNKOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. There can be many overlapped I/O operations outstanding when an I/O completion port is 
destroyed. The buffers that are associated with these overlapped I/O operations are available for use 
by the application as soon as QsoDestroyIOCompletionPort()returns successfully. 


2. The state of the sockets that were used to issue the overlapped I/O operations that are still 
outstanding is not defined. That is, there is no way for the application to determine if an 
outstanding QsoStartRecv() or QsoStartSend() has completed once the I/O completion port has 
been destroyed. For this reason, further attempts to read from those sockets will result in 
ECONNABORTED and further attempts to write to these sockets will result in EPIPE. No further 
input or output operations will be allowed on these sockets. 


Related Information 


e@ QsoCreatelOCompletionPort()--Create I/O Completion Port 


@ QsoPostlOCompletionPort()--Post Request on I/O Completion Port 


e@ QsoStartRecv--Start Asynchronous Recv Operation 


e@ QsoStartSend--Start Asynchronous Send Operation 


e@ QsoWaitForlIOCompletionQ--Wait for I/O Completion Operation 


API Introduced: V5R1 
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QsoPostlOCompletion()--Post I/O Completion Request 


Syntax 


#include <qsoasync.h> 


int QsoPostIOCompletion 
(int IOCompletionPort, Qso_OverlappedIO_t * communicationsArea) 


Service Program Name: QSOSRV3 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsoPostIOCompletion function will post an Qso_OverlappedIO_t request on a specifed I/O completion port. This allows an 
application to notify a completion port that some function or activity has occurred. The application defines what that function or 
activity is within the Qso_OverlappedIO_t request. 


Parameters 


int IOCompletionPort (Input) 
The I/O completion port that should be posted. 


Qso_OverlappedIO_t * communicationsArea (Input/Output) 


A pointer to a structure that contains the following information: 


descriptorHandle (Input) - The descriptor handle is application-specific and is never used by the system. It is 
intended to make it easier for the application to keep track of information regarding a given 
socket connection. 


buffer (Input) - Supplied value is preserved. 
bufferLength (Input) - Supplied value is preserved. 
postFlag (Input) - Supplied value is preserved. 
fillBuffer (Input) - Supplied value is preserved. 
returnValue (Output) - This field will be set to 0 if this operation completes successfully. 
errnoValue (Output) - This field will be set to 0 if this operation completes successfully. 


operationCompleted (Output) - This field is updated to QSOPOSTIOCOMPLETION. 


> Not used. 
secureDataTransferSize 


bytesAvailable Not used. 


operationWaitTime 


postedDescriptor 


reserved] 


reserved2 


Authorities 


No authorization is required. 


Return Values 


(Input) - A timeval structure which specifies a time to wait before posting this operation 
asynchronously to the I/O completion port with errnoValue set to EAGAIN. 


struct timeval { 
long tv_sec; /* second */ 
long tv_usec; /* microseconds x] 


de 
If this field is set to zero, the operation will be posted immediately. 


If postedDescriptor is closed before the timer expires, the operation will be posted to the I/O 
completion port with errnoValue set to ECLOSED. 


The minimum operationWaitTime is 1 second. The microseconds field (tv_usec) in the timeval 
is not used and must be set to zero. 


This field is only relevant if a non-zero timeval was specified in operationWaitTime. This is the 
socket descriptor to be associated with the timer. If this descriptor is closed before the timer 
expires, the operation will be posted to the I/O completion port with errnoValue set to 
ECLOSED.& 


(Input) - Must be set to hex zeroes. 


(Input) - Must be set to hex zeroes. 


QsoPostIOCompletion() returns an integer. Possible values are: 


e -1 - The function did not complete because an error occurred. Inspect the errno value to determine the cause of the failure. 


e 0- The function has successfully posted the communications area to the I/O completion port. 


e@ » 1 - The timer has been started. When the timer expires the Qso_OverlappedIO_t communications structure will be 
updated with the results and the I/O completion port will be posted. & 


Errno Conditions 


When QsoPostIOCompletion() fails, errno can be set to one of the following: 


[EINVAL] The I/O completion port or a reserved field was specified that was not valid # or operationWaitTime.tv_sec 
was negative or operationWaitTime.tv_usec was not zero. « 


[EDESTROYED] The I/O completion port has been destroyed. 


[ENOBUFS] There was not enough buffer space for the requested operation. Check the maximum allowed storage for the 
executing user profile. 


[ENOMEM] The I/O completion port is full and cannot accept any more messages at this time. 


Error Messages 


Message ID Error Message Text 

CPFA081 E Unable to set return value or error code. 

CPE3418 E Possible APAR condition or hardware failure. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Related Information 


e@ QsoCreatelOCompletionPort()--Create I/O Completion Port 


e@ QsoDestroyIOCompletionPort()--Destroy I/O Completion Port 


e@ QsoStartRecv--Start Asynchronous Recv Operation 


e@ QsoStartSend--Start Asynchronous Send Operation 


@ QsoWaitForIOCompletion(--Wait for I/O Completion Operation 


API Introduced: V5R1 
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QsoStartAccept()--Start asynchronous accept operation 


Syntax 


#include <sys/socket.h> 
#include <qsoasync.h> 


int QsoStartAccept (int socketDescriptor,int IOCompletionPort, 
Qso_OverlappedIO_t * communicationsArea) 


Service Program Name: QSOSRV3 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsoStartAccept() function is used to wait asynchronously for connection requests. If connection requests are queued, then 
QsoStartAccept() takes the first connection request on the queue and creates a new socket to service the connection request. If no 
connection requests are queued, then an asynchronous QsoStartAccept() request is pended onto the socket and will be transition to the 
specified I/O completion port once a connection arrives. This API only supports sockets with an address family of AF_INET or 
AF_INET6& and type SOCK_STREAM. 


Parameters 


socketDescriptor (Input) 


The descriptor of the socket on which to wait. 


int I[OCompletionPort(Input) 
The I/O completion port that should be posted when the operation completes. 


Qso_OverlappedIO_t* communicationsArea (Input/Output) 


A pointer to a structure that contains the following information: 


descriptorHandle (Input) - The descriptor handle is application specific and is never used by the system. This 
field is intended to make it easier for the application to keep track of information regarding a 
given socket connection. 


buffer Not used. 
bufferLength Not used. 
postFlag (Input) - The postFlag indicates if this operation should be posted to the I/O completion port 


even if it completes immediately. 


o A 0 value indicates that if the operation is already complete upon return to the 
application, then do not post to the I/O completion port. 


o A 1 value indicates that even if the operation completes immediately upon return to the 
application, the result should still be posted to the I/O completion port. 


postFlagResult (Output) - This field is valid if QsoStartAccept() returns with 1 and postFlag was set to 1. In 
this scenario, postFlagResult set to 1 denotes the operation completed and has been posted to 
the I/O completion port specified. A value of 0 denotes the operation could not be completed 
immediately, but will be handled asynchronously. 


ilBuffer Not used. 
fi 


returnValue When QsoStartAccept() completes synchronously (function return value equals 0), then this 
field identifies the socket descriptor associated with the accepted connection. When the accept 
operation completes asynchronously, this field contains indication of success or failure. 


errnoValue (Output) - When the operation completes asynchronously and returnValue is negative, this field 
will contain an errno to indicate the error with which the operation eventually failed. 


operationCompleted (Output) - If the operation is posted to the I/O completion port, this field is updated to indicate 
that the operation was a QSOSTARTACCEPT. 


secureDataTransferSize Not used. 


bytesAvailable (Output) - Number of bytes available to be read from connection. Only valid if return Value is 
>=0. 

> 

operationWaitTime (Input) - A timeval structure which specifies the maximum time allowed for this operation to 


complete asynchronously. 


struct timeval { 
long tv_sec; /* second */ 
long tv_usec; /* microseconds */ 


}; 


If this timer expires, the operation will be posted to the I/O completion port with errnoValue set 
to EAGAIN. 


If this field is set to zero, the operation's asynchronous completion will not be timed. 


If socketDescriptor is closed before the operation completes or times out, the operation will be 
posted to the I/O completion port with errnoValue set to ECLOSED. 


The minimum operationWaitTime is 1 second. The microseconds field (tv_usec) in the timeval 
is not used and must be set to zero. 


postedDescriptor Not used - Must be set to zero. « 
reserved] (Output) - Must be set to hex zeroes. 
reserved2 (Input) - Must be set to hex zeroes. 

Authorities 


No authorization is required. 


Return Values 


QsoStartAccept() returns an integer. Possible values are: 
e -1 - The function was not started because an error occurred. Inspect the errno to determine the cause of the failure. 


e 0- The function has already completed. The Qso_OverlappedIO_t communications structure has been updated but nothing has or 
will be posted to the I/O completion port for this operation. Inspect the return Value in the Qso_OverlappedIO_t communications 
structure to obtain connection descriptor and bytesAvailable. 


e 1 - The function has been started. When the function completes (or times out if operationWaitTime was specified), “ the 
Qso_OverlappedIO_t communications structure will be updated with the results and the I/O completion port will be posted. 


Errno Conditions 
When QsoStartAccept() fails, errno can be set to one of the following: 


[EFAULT] Bad address 


[EINVAL] A I/O completion port or reserved field specified was not valid or postedDescriptor was not zero or 
operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec was not zero, “ or a Listen() has not 
been issued against the socket referenced by the SocketDescriptor parameter. 


[EACCES] Permission denied. 


A connection indication request was received on the socket referenced by the socket_descriptor parameter, but 
the process that issued the QsoStartAccept() did not have the appropriate privileges required to handle the 
request. The connection indication request is reset by the system. 


[EBADF] Descriptor not valid. 


[ECONNABORTED] Connection ended abnormally. 


An QsoStartAccept() was issued on a socket for which receives have been disallowed (due to a shutdown() 


call). 
[EIO] Input/output. 
[EMFILE] Too many descriptors for this process. 
[ENFILE] Too many descriptors in system. 
[ENOBUFS] There is not enough buffer space for the requested operation. 
[ENOTSOCK] The specified descriptor does not reference a socket. 


[EOPNOTSUPP] Operation not supported. 


The socket_descriptor parameter references a socket that does not support the QsoStartAccept(). The 
QsoStartAccept() is only valid on sockets with an address family of AF_INET or AF_INET6&% and type 
SOCK_STREAM. 


The socket_descriptor parameter references a socket that has undergone an Rbind(). The QsoStartAccept() 
operation is not valid on sockets in this state. 


[EUNATCH] The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPFA081 E Unable to set return value or error code. 
CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. It is not recommended to intermix QsoStartAccept() and accept(). If this condition occurs, the order the requests will be serviced 
is undefined. 


2. The following are inherited by the descriptor returned by the accept() call: 
Oo All socket options with a level of SOL_SOCKET. 
oO. The status flags: 


m Blocking flag (set/reset either by the ioc/tl() call with the FIONBIO request or by the fentl() call with the 
F_SETFL command and the status flag set to O_.NONBLOCK). 


m Asynchronous flag (set/reset either by the ioctl() call with the FIOASYNC request or by the fentl() call with the 
F_SETFL command and the status flag set to FASYNC). 


o The process ID or process group ID that is to receive SIGIO or SIGURG signals (set/reset by either the ioctl() call with 
the FIOSETOWN or the SIOCSPGRP request, or by the fcntl() call with the FSSETOWN command). 


3. Closing a socket causes any queued but unaccepted connection requests to be reset. 


Related Information 


@ accept()--Accept Connection 


e@ QsoCreatelOCompletionPort()--Create I/O Completion Port 


e@ QsoDestroyIOCompletionPort()--Destroy I/O Completion Port 


e@ QsoPostIOCompletionPort()--Post Request on I/O Completion Port 


e@ QsoStartSend--Start Asynchronous Send Operation 


e@ QsoWaitForIOCompletion(--Wait for I/O Completion Operation 


@ recv()--Receive Data 
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QsoStartRecv()--Start Asynchronous Receive Operation 


Syntax 


#include <qsoasync.h> 


int QsoStartRecv (int socketDescriptor,int I0CompletionPort, 
Qso_OverlappedIO_t * communicationsArea) 


Service Program Name: QSOSRV3 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsoStartRecv function is used to initiate a asynchronous receive operation. The supplied buffer cannot be reused by the calling 
application until the receive is complete or the I/O completion port specified on the QsoStartRecv has been destroyed. This API only 
supports sockets with an address family of AF_INET or AF_INET6® and type SOCK_STREAM. 


Parameters 


int socketDescriptor (Input) 


The socket descriptor that should be used to receive data into the specified buffer. 


int [OCompletionPort (Input) 
The I/O completion port that should be posted when the operation completes. 


Qso_OverlappedIO_t * communicationsArea (Input/Output) 


A pointer to a structure that contains the following information: 


descriptorHandle (Input) - The descriptor handle is application specific and is never used by the system. This 
field is intended to make it easier for the application to keep track of information regarding a 
given socket connection. 


buffer (Input) - A pointer to a buffer into which data should be read. 


bufferLength (Input) - The length of the buffer into which data should be read. Also represents the amount of 
data requested. 


postFlag (Input) - The postFlag indicates if this operation should be posted to the I/O completion port 
even if it completes immediately. 


Oo A 0 value indicates that if the operation is already complete upon return to the 
application, then do not post to the I/O completion port. 


oO A 1 value indicates that even if the operation completes immediately upon return to the 
application, the result should still be posted to the I/O completion port. 


postFlagResult (Output) - This field is valid if QsoStartRecv() returns with | and postFlag was set to 1. In this 
scenario, postFlagResult set to 1 denotes the operation completed and been posted to the I/O 
completion port specified. A value of 0 denotes the operation could not be completed 
immediately, but will be handled asynchronously. 


fillBuffer (Input) - The fillBuffer flag indicates when this operation should complete. If the fillBuffer flag 
is 0, then the operation will complete as soon as any data is available to be received. If the 
fillBuffer flag is non-zero, this operation will not complete until enough data has been received 
to fill the buffer, an end-of-file condition occurs on the socket, or an error occurs on a socket. 


returnValue (Output) - When QsoStartRecv() completes synchronously (function return value equals 0), 
then this field indicates the number of bytes that were actually received. When the recv 
operation completes asynchronously, this field contains indication of success or failure. Zero 
returned denotes end-of-file state. 


errnoValue (Output) - When the operation completes asynchronously and returnValue is negative, this field 
contains an errno to indicate the error with which the operation eventually failed. 


operationCompleted (Output) - If the operation is posted to the I/O completion port, this field is updated to indicate 
that the operation was a QsoStartRecv(). 

> Not used. 

secureDataTransferSize 

bytesAvailable Not used. 

operationWaitTime (Input) - A timeval structure which specifies the maximum time allowed for this operation to 


complete asynchronously. 


struct timeval { 
long tv_sec; /* second e/ 
long tv_usec; /* microseconds */ 


}; 


If this timer expires, the operation will be posted to the I/O completion port with errnoValue set 
to EAGAIN. 


If this field is set to zero, the operation's asynchronous completion will not be timed. 


If socketDescriptor is closed before the operation completes or times out, the operation will be 
posted to the I/O completion port with errnoValue set to ECLOSED. 


The minimum operationWaitTime is 1 second. The microseconds field (tv_usec) in the timeval 
is not used and must be set to zero. 


postedDescriptor Not used - Must be set to zero. < 
reserved] (Input) - Must be set to hex zeroes. 
reserved2 (Input) - Must be set to hex zeroes. 

Authorities 


No authorization is required. 


Return Values 


QsoStartRecv() returns an integer. Possible values are: 
e -1 - The function was not started because an error occurred. Inspect the errno to determine the cause of the failure. 


e 0- The function has already completed. The Qso_OverlappedIO_t communications structure has been updated but nothing has or 
will be posted to the I/O completion port for this operation. Inspect the return Value in the Qso_OverlappedIO_t communications 
structure to determine the number of bytes received. 


e | - The function has been started. When the function completes % (or times out if operationWaitTime was specified), “ the 
Qso_OverlappedIO_t communications structure will be updated with the results and the I/O completion port will be posted. 


Errno Conditions 


When QsoStartRecv() fails, errno can be set to one of the following: 


[EINVAL] _ A buffer length or I/O completion port or reserved field specified was not valid or postedDescriptor was not zero or 
operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec was not zero. & 


[ETRUNC] | Data was truncated on an input, output, or update operation. Data has been lost. 


Note: The rest of the errno values from recv(Q) also apply to QsoStartRecv(). 


Error Messages 


Message ID 
CPFA081 E 
CPE3418 E 
CPF9872 E 


Error Message Text 
Unable to set return value or error code. 
Possible APAR condition or hardware failure. 


Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. If QsoStartRecv() partially fills a buffer and then encounters an EFAULT condition, the QsoStartRecv() will complete with the 
ETRUNC error value to indicate that some data has been lost. 


2. A buffer that is given to QsoStartRecv() must not be used by the application again until either it is returned by 
QsoWaitForIOCompletion() or is reclaimed by issuing a close() on the socket descriptor or issuing a 
QsoDestroyIOCompletionPort() on the I/O completion port. If a buffer is given to QsoStartRecv() to be filled, and it is later 
detected during QsoStartRecv processing that the buffer has been freed, it may produce an unrecoverable condition on the socket 
for which the QsoStartRecv() was issued. If this occurs, am ECONNABORTED error value will be returned. 


3. It is not recommended to intermix QsoStartRecv() and blocking I/O (that is, recv()) on the same socket. If this condition occurs, 
then pending asynchronous send I/O will be serviced first before the blocking I/O. 


4. Socket option SO.RCVLOWAT is not supported by this API. Semantics similar to SO RCVLOWAT can be obtained using the 
fillBuffer field in the Qso_OverLappedIO_t structure. 


5. Socket option SO_LRCVTIMEO is not supported by this API. Semantics similar to SOLRCVTIMEO can be obtained using the 
operationWaitTime field in the Qso_OverLappedIO_t structure. & 


Related Information 


e@ QsoCreatelOCompletionPort()--Create I/O Completion Port 


e@ QsoDestroyIOCompletionPort()--Create I/O Completion Port 


e@ QsoPostIOCompletionPort()--Post Request on I/O Completion Port 


e QsoStartSend--Start Asynchronous Send Operation 


e@ QsoWaitForIOCompletion()--Wait for I/O Completion Operation 


@ recv()--Receive Data 
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QsoStartSend()--Start Asynchronous Send Operation 


Syntax 


#include <qsoasync.h> 


int QsoStartSend (int socketDescriptor, int IOCompletionPort, 
Qso_OverlappedIO_t * communicationsArea) 


Service Program Name: QSOSRV3 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsoStartSend function is used to initiate a asynchronous send operation. The supplied buffer cannot be reused by the calling application 
until the send is complete or the I/O completion port specified on the QsoStartSend has been destroyed. This API only supports sockets with 
an address family of AF_INET or AF_INET6& and type SOCK_STREAM. 


Parameters 


int socketDescriptor (Input) 
The socket descriptor on which the data should be sent. 


int IOCompletionPort(Input) 
The I/O completion port that should be posted when the operation completes. 


Qso_OverlappedIO_t * communicationsArea (Input/Output) 


A pointer to a structure that contains the following information: 


descriptorHandle (Input) - The descriptor handle is application specific and is never used by the system. This 
field is intended to make it easier for the application to keep track of information regarding a 
given socket connection. 


buffer (Input) - A pointer to a buffer of data that should be sent over the socket. 
bufferLength (Input) - The length of the data to be sent. 
postFlag (Input) - The postFlag indicates if this operation should be posted to the I/O completion port 


even if it completes immediately. 


o AO value indicates that if the operation is already complete upon return to the 
application, then do not post to the I/O completion port. 


o A 1 value indicates that even if the operation completes immediately upon return to the 
application, the result should still be posted to the I/O completion port. 


postFlagResult (Output) - This field is valid if QsoStartSend() returns with 1 and postFlag was set to 1. In this 
scenario, postFlagResult set to 1 denotes the operation completed and been posted to the I/O 
completion port specified. A value of 0 denotes the operation could not be completed 
immediately, but will be handled asynchronously. 


‘fillBuffer (Input) - Only used on QsoStartRecv(). Ignored on QsoStartSend(). 


returnValue (Output) - When QsoStartSend() completes synchronously (function return value equals 0), 
then this field indicates the number of bytes that was actually sent. When the send operation 
completes asynchronously, this filed contains indication of success or failure. 


errnoValue (Output) - When the operation completes asynchronously and returnValue is negative, this field 
will contain an errno to indicate the error with which the operation eventually failed. 


operationCompleted (Output) - If the operation is posted to the I/O completion port, this field is updated to indicate 
that the operation was a QsoStartSend(). 


> secureDataTransferSize Not used. 
bytesAvailable Not used. 


operationWaitTime (Input) - A timeval structure which specifies the maximum time allowed for this operation to 
complete asynchronously. 


struct timeval { 
long tv_sec; /* second */ 
long tv_usec; /* microseconds *«/ 
hi 


If this timer expires, the operation will be posted to the I/O completion port with errnoValue set 
to EAGAIN. 


If this field is set to zero, the operation's asynchronous completion will not be timed. 


If socketDescriptor is closed before the operation completes or times out, the operation will be 
posted to the I/O completion port with errnoValue set to ECLOSED. 


The minimum operationWaitTime is | second. The microseconds field (tv_usec) in the timeval 
is not used and must be set to zero. 


postedDescriptor Not used - Must be set to zero. « 
reserved] (Input) - Must be set to hex zeroes. 
reserved2 (Input) - Must be set to hex zeroes. 

Authorities 


No authorization is required. 


Return Values 


QsoStartSend() returns an integer. Possible values are: 
e -1 - The function was not started because an error occurred. Inspect the errno to determine the cause of the failure. 


e@ 0- The function has already completed. The Qso_OverlappedIO_t communications structure has been updated but nothing has or 
will be posted to the I/O completion port for this operation. Inspect the returnValue in the Qso_OverlappedIO_t communications 
structure to determine the number of bytes sent. 


e | - The function has been started. When the function completes (or times out if operationWaitTime was specified), & the 
Qso_OverlappedIO_t communications structure will be updated with the results and the I/O completion port will be posted. 


Errno Conditions 


When QsoStartSend() fails, errno can be set to one of the following: 


[EINVAL] A buffer length or I/O completion port or reserved field specified was not valid % or postedDescriptor was not zero or 
operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec was not zero. & 


Note: The rest of the errno values from send() also apply to QsoStartSend(). 


Error Messages 


Message ID Error Message Text 
CPFA081 E Unable to set return value or error code. 
CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. It is important for application programmers to keep in mind that since QsoStartSend() is asynchronous, care should be used to 
control how many of these functions are outstanding. When a TCP socket becomes flow control blocked such that the 
QsoStartSend() is not able to pass the data to the TCP socket immediately, the return value will be 1. Applications that send large 
amounts of data should have the postFlag set to 0. This allows the application to use a return value of 1 as an indication that the 
socket has become flow control blocked. The application should then wait for the outstanding operation to complete before issuing 
another QsoStartSend(). This will ensure that the application does not exhaust system buffer resources. 


2. A buffer that is given to QsoStartSend() must not be used by the application again until either it is returned by 
QsoWaitForIOCompletion() or is reclaimed by issuing a close() on the socket descriptor or issuing a 
QsoDestroyIOCompletionPort() on the I/O completion port. If a buffer is given to QsoStartSend() to be sent, and it is later detected 
during QsoStartSend() processing that the buffer has been freed, it may produce an unrecoverable condition on the socket for which 
the QsoStartSend() was issued. If this occurs, am ECONNABORTED error value will be returned. 


3. It is not recommended to intermix QsoStartSend() and blocking I/O (that is, send()) on the same socket. If one does, then the 
pending asynchronous send I/O will be serviced before blocking I/O once data can be sent. 


4. Socket option SO_SNDTIMEO is not supported by this API. Semantics similar to SO.LSNDTIMEO can be obtained using the 


operationWaitTime field in the Qso_OverLappedIO_t structure. & 


Related Information 


@ QsoCreatelOCompletionPort()--Create I/O Completion Port 


e@ QsoDestroyI[OCompletionPort()--Destroy I/O Completion Port 


e@ QsoPostlOCompletionPort()--Post Request on I/O Completion Port 


e@ QsoStartRecv--Start Asynchronous Recv Operation 


e@ QsoWaitForlOCompletion()--Wait for I/O Completion Operation 


e@ send()--Send Data 
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QsoWaitForlOCompletion()--Wait for I/O Operation 


Syntax 


#include <gskssl.n> 
#include <qsoasync.h 


int QsoWaitForIOCompletion (int IOCompletionPort, 


Qso_OverlappedIO_t * completionStatus, 
struct timeval * timeToWait) 


Service Program Name: QSOSRV3 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsoWaitForIOCompletion() is used to wait for a completed overlapped I/O operation. The wait point is represented 


by the I/O completion port that was created using the QsoCreatelOCompletionPort() function. 


Parameters 


int [OCompletionPort 
(Input) The I/O completion port on which to wait. 


Qso_OverlappedIO_t * completionStatus 


(Input/Output) A pointer to a qso_overlappedIO_t structure that will be updated with the status defined below. I 
a field has no relevance to operationCompleted, then either a null or zero will be returned for that field. 


descriptorHandle (Ouput) The descriptor handle that was supplied by the application when the operation 
was started. 


buffer (Ouput) A pointer to the buffer that was supplied when the operation was started. Null is 
returned when operationCompleted is Q3OSTARTACCEPT # or 
GSKSECURESOCSTARTINIT 8. 


bufferLength (Ouput) The length of the buffer that was supplied when the operation was started. Zero 
is returned when operationCompleted is Q9OSTARTACCEPT #2 or 
GSKSECURESOCSTARTINIT &&. 


postF lag (Ouput) The value of the postFlag when the operation was started. Zero is returned when 
operationCompleted is Q3OSTARTACCEPT # or GSKSECURESOCSTARTINIT &. 


illBuffer (Ouput) The value of the fillBuffer when the operation was started. Zero is returned when 
L p P 
operationCompleted is Q3OSTARTACCEPT 3 or GSKSECURESOCSTARTINIT &. 


f 


returnValue (Output) 


o Possible values if operationCompleted is QSOPOSTIOCOMPLETION,& 
QSOSTARTRECV, QSOSTARTSEND, or QSOSTARTACCEPT: 


-1 The operation failed and errnoValue field should be checked for 
further explanation of the error. 


>=0 For both QSOSTARTRECV and QSOSTARTSEND, indicates the 
number of bytes sent or received respectively. A return value of 0 on a 
receive indicates an end-of-file condition. For Q9OSTARTACCEPT, 
this field is the socket connection descriptor. #* For 
QSOPOSTIOCOMPLETION, a return value of 0 indicates the 
operation was not timed (operationWaitTime was zero on input). 
QSOPOSTIOCOMPLETION will not return > 0. 


oO Possible values if operationCompleted is GSKSECURESOCSTARTSEND or 
GSKSECURESOCSTARTRECV: 


GSK_OK Operation was successful. Field secureDataTransferSize indicates 
the number of bytes sent or received respectively. 


Failure 


m= Possible values common to GSGKSECURESOCSTARTSEND and 
GSKSECURESOCSTARTRECV: 


[GSK_AS400_ERROR_INVALID_POINTER] The buffer pointer 
located in the 
Qso_OverLappedIO_t 
is not valid. 


[GSK_INTERNAL_ERROR] An unexpected error 
occurred during SSL 
processing. 


[GSK_AS400_ERROR_CLOSED] Secure session was 
closed by a thread 
during SSL 
processing. 


[GSK_ERROR_IO] An error occurred in 
SSL processing; 
check the errno value. 


[GSK_ERROR_SOCKET_CLOSED] A close() was done on 
the socket descriptor 
for this secure 
session. 


m Values unique to GDKSECURESOCSTARTRECV: 


[GSK_INVALID_HANDLE] The handle specified was not 
valid. 


[GSK_INVALID_STATE] The handle is not in the correct 
state for this operation. 


[GSK_ERROR_BAD_MESSAGE] SSL received a badly formatted 
message. 


[GSK_ERROR_BAD_MAC] A bad message authentication 
code was received. 


o Possible values if operationCompleted is GSKSECURESOCSTARTINIT: 


[GSK_OK] Operation was successful, a secure 
session established. 


[GSK_ERROR_BAD_MESSAGE] SSL received a badly formatted 
message. 
[GSK_ERROR_BAD_MAC] A bad message authentication 


code was received. 


[GSK_KEYRING_OPEN_ERROR] Certificate store file could not be 
opened. 


[GSK_ERROR_BAD_KEYFILE_LABEL] The specified certificate store 
label is not valid. 


[GSK_ERROR_BAD_V3_CIPHER] An SSLV3 or TLSV1 cipher suite 
was specified that is not valid. 


[GSK_ERROR_BAD_V2_CIPHER] An SSLV2 cipher suite was 
specified that is not valid. 


[GSK_ERROR_NO_CIPHERS] No ciphers available or no ciphers 
were specified. 


[GSK_ERROR_NO_CERTIFICATE] No certificate is available for SSL 
processing. 


[GSK_ERROR_BAD_CERTIFICATE] The certificate is bad. 


[SSLLERROR_NOT_TRUSTED_ROOT] _ The certificate is not signed by a 
trusted certificate authority. 


[GSK_KEYFILE_CERT_EXPIRED] The validity time period of the 
certificate has expired. 


[GSK_ERROR_BAD_MESSAGE] A badly formatted message was 
received. 
[GSK_ERROR_UNSUPPORTED] Operation is not supported by 
SSL. 
[GSK_ERROR_BAD_PEER] The peer system is not recognized. 
[GSK_ERROR_CLOSED] The SSL session ended. 


[GSK_AS400_ERROR_TIMED_OUT] The value specified for the 
handshake timeout expired before 
the handshake completed. 


[GSK_INSUFFICIENT_STORAGE] Unable to allocate storage for the 
requested operation. 


“s 


errnoValue 


(Output) If operationCompleted is 2QSOPOSTIOCOMPLETION,*“& QSOSTARTSEND, 
QSOSTARTRECYV or QSOSTARTACCEPT and returnValue is negative, this field will contain an errno 
value further defining the error. This is also true if operationCompleted is GSKSECURESOCSTARTSEND or 
GSKSECURESOCSTARTRECYV and returnValue is GSK_ERROR_IO. 


Possible values are: 
= If operationCompleted is QQOPOSTIOCOMPLETION: 


[EAGAIN] The specified timer value expired. 


[ECLOSED] The socket descriptor was closed before the timer expired. 
4 
If operationCompleted is QQOSTARTRECV or GSKSECURESOCSTARTRECV: 


[EAGAIN] The operation did not complete in the specified time. 
[EIO] Input/output error. 


[ECONNABORTED] Connection ended abnormally. 
This error code indicates that the transport provider ended the connection abnormally 
because of one of the following: 


o. The retransmission limit has been reached for the data that was being sent on 
the socket. 


o A protocol error was detected. 


[ECONNRESET] A connection with a remote socket was reset by that socket. 


[ECLOSED] Connection was closed. Only valid for QS OSTARTRECV. 


[EFAULT] Read buffer pointer not valid. 


If operationCompleted is QSOSTARTSEND or GSKSECURESOCSTARTSEND: 


[EAGAIN] The operation did not complete in the specified time. 


[EIO] Input/output error. 


[EPIPE] Broken pipe. 


[ECLOSED] Connection was closed. Only valid for QQOSTARTSEND 


[EFAULT] Send buffer pointer not valid. 


If operationCompleted is Q9SOSTARTACCEPT: 


[EAGAIN] The operation did not complete in the specified time. 


[ECONNABORTED] Connection ended abnormally. 


[ECLOSED] Listening socket closed. 

[EIO] Input/output error. 

[EMFILE] Too many descriptors for this process. 

[ENFILE] Too many descriptors in system. 

[ENOBUFS] There is not enough buffer space for the requested operation. 
[EUNKNOWN] Unknown system state. 


2If operationCompleted is GIKSECURESOCSTARTINIT: 


[ECONNABORTED] Connection ended abnormally. 
[EDEADLK] Resource deadlock avoided. 
[EINTR] Interrupted function call. 


[EIO] Input/output error. 


[ETERM] 


[EUNATCH] 


Operation terminated. 


The protocol required to support the specified address family is not available at € 
this time. 


# Any errno that can be returned by send() or recv() can be returned by this API if operationCompleted is 
GSKSECURESOCSTARTINIT. See Sockets APIs for a description of the errno values they return. 


If an errno is returned that is not in this list, see Errno Values for UNIX-Type Functions for a description of the 


errno.& 


secureDataTransferSize 


bytesAvailable 


operationWaitTime 


postedDescriptor 


operationCompleted 


struct timeval * timeToWait 


(Output) Number of bytes received or sent if operationCompleted is 
GSKSECURESOCSTARTRECV or GSKSECURESOCSTARTSEND 
respectively and returnValue equals GSK_OK. 


(Output) Number of bytes available to be read from connection. This parameter is 
valid only if operationCompleted is QSOSTARTACCEPT and returnValue is >= 
0. 


(Ouput) The value of the operationWaitTime when the operation was started. 


(Ouput) Always set to negative one. This field is only used on input for 
QsoPostIOCompletion(). When the operation is retrieved with 
QsoWaitForIOCompletion(), the descriptorHandle should be used to identify the 
socket connection and not this field.“ 


(Output) The operation that was started and has now completed. 


m | (QSOSTARTSEND) 
2 (QSOSTARTRECV) 

3 (QSOPOSTIOCOMPLETION) 

4 (GSKSECURESOCSTARTSEND) 

5 (GSKSECURESOCSTARTRECV) 

6 (QSOSTARTACCEPT) 

2#°7 (GSKSECURESOCSTARTINIT) 


(Input) A pointer to a timeval structure that contains the time in seconds and microseconds for which the 
QsoWaitForIOCompletion() call should block if there is no completion status to receive. 


If this parameter is null, QsoWaitForIOCompletion() waits indefinitely. If this value is specified, and 0 seconds 
0 microseconds are specified, QsoWaitForIOCompletion() returns immediately. 


Authorities 


» Authorization of *R (allow access to the object) to the certificate store file and its associated files is required. 
Authorization of *X (allow use of the object) to each directory of the path name of the certificate store file and its 


associated files is required. 


Return Values 


QsoWaitForIOCompletion returns an integer. Possible value are: 


I Completion of an overlapped I/O function has been returned. 
-1 The QsoWaitForIOCompletion() function timed out or an error occurred. Errno value has been set. 


0 If the QsoWaitForIOCompletion() function is issued with a timeToWait parameter that specifies 0 seconds 0 
microseconds and there is no completion status to report, the function returns immediately with a return value of 
zero. 


Errno Conditions 


When QsoWaitForIOCompletion fails, errno can be set to one of the following: 


[ETIME] The function has blocked for the time period specified and has no completion status to report. 


[EFAULT] Bad address. The system detected a bad address while attempting to access the completionStatus 
or the timeToWait parameter. 


[EDESTROYED] The I/O completion port has been destroyed. 
[EINVAL] The value of the I/O completion port is not valid or the timeToWait parameter is not valid. 
[EINTR] Interrupted function call. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPFA081 E Unable to set return value or error code. 
CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


Usage Notes 


1. An errno of EDESTROYED indicates that the thread was waiting on the I/O completion port at the time that it 
was destroyed by another thread. When an I/O completion port is destroyed, all buffers that are associated with 
outstanding overlapped I/O operations are immediately available for use by the application program. 


2. The application should first check the return value of the QsoWaitForIOCompletion() call to determine if the 
Qso_OverlappedIO_t structure specified by the completionStatus parameter has been updated. This structure is 
updated ONLY if the return value of the QsoWaitForIOCompletion() call is one (1). 


Related Information 


e@ QsoCreatel[OCompletionPort()--Create I/O Completion Port 


e@ QsoDestroyI[OCompletionPort()--Create I/O Completion Port 


e@ QsoPostIOCompletionPort()--Post Request on I/O Completion Port 


e@ QsoStartAccept()--Start asynchronous accept operation 


e QsoStartRecv()--Start Asynchronous Recv Operation 


e@ QsoStartSend()--Start Asynchronous Send Operation 


e@ gsk_secure_soc_startRecv()--Start Asynchronous Receive Operation on a Secure Session 


e@ gsk secure _soc_startSend()--Start Asynchronous Send Operation on a Secure Session 


e@ #esk_secure_soc_startInit()--Start asynchronous operation to negotiate a secure session®& 


API Introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


Rbind()--Set Remote Address for Socket 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int Rbind(int socket_descriptor, 


struct sockaddr *local_address, 
int address_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int Rbind(int socket_descriptor, 


const struct sockaddr *local_address, 
socklen_t address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 
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A program uses the Rbind() call to request that a SOCKS server allow an inbound connection request 
across a firewall. This call should only be used by applications that require inbound connections across a 
firewall, and should only be used for sockets with an address family of AF_INET. Note that for an Rbind() 
call to succeed, a previous connect() call must have been issued for this thread, and must have resulted in an 
outbound connection over the same SOCKS server. The Rbind() inbound connection will be from the same 
IP address addressed by the original outbound connection. Caution must be exercised so that outbound and 
inbound connections over the SOCKS server are paired. In other words, all Rbind() inbound connections 
should immediately follow the outbound connection over the SOCKS server, and no intervening 
non-SOCKS connections relating to this thread can be attempted before the Rbind() runs. For an overview 
of using sockets and how to interact with a SOCKS server, see the topic about OS/400 client SOCKS 
support in the Sockets Programming in the iSeries Information Center. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 


syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


socket_descriptor 


(Input) The descriptor of the socket that is to be bound. 


local_address 


(Input) A pointer to a buffer of type struct sockaddr that contains the local address to which the 
socket is to be bound. The structure sockaddr is defined in <sys/socket.h>. 


#* The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


fae 


The BSD 4.4 sa_len field is the length of the address. The sa_family field identifies the address 
family to which the address belongs, and sa_data is the address whose format is dependent on the 
address family. 


address_length 
(Input) The length of the local_address. 


Authorities 


e@ When the address type of the socket identified by the socket_descriptor is AF_INET, the thread 
must have retrieve, insert, delete, and update authority to the port specified by the local_address 
field. When the thread does not have this level of authority, an errno of EACCES is returned. 


e@ When the address type of the socket identified by the socket_descriptor is AF_INET and is running 
IP over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. 
When the thread does not have this level of authority, an errno of EACCES is returned. 


Return Value 


Rbind() returns an integer. Possible values are: 


e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When an Rbind() fails, errno can be set to one of the following: 


[EADDRNOTAVAIL] Address not available. This error code indicates one of the following: 
e@ The SOCKS server specified is not reachable. 


e The SOCKS server has denied the requested inbound connection. 


e The Socket can no longer be used for an inbound connection. 
[EAFNOSUPPORT] _ The type of socket is not supported in this protocol family. 


The address family specified in the address structure pointed to by the 
local_address parameter cannot be used with the socket pointed to by the 
socket_descriptor parameter. 


[EBADF] Descriptor not valid. 


[EFAULT] Bad address. 


The system detected an address that was not valid while attempting to access the 
local_address parameter. 


[EINVAL] Parameter not valid. This error code indicates one of the following: 


e The address_length parameter specifies a length that is negative or is 
not valid for the address family. 


e The socket referenced by socket_descriptor is not a socket of type 
SOCK_RAW and is already bound to an address. 


e The local address pointed to by the /ocal_address parameter specified an 
address that was not valid. 


[EIO] Input/output error. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTSOCK] The specified descriptor does not reference a socket. 


[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. If this call is issued for sockets with an address family other than AF_INET, or if the thread has not 
performed an outbound connection through a SOCKS server, then a bind() call will be run instead. 
In this case the documented errno and usage notes for bind() apply. 


2. The local IP address and port number specified for sockets with an address family of AF_INET are 
ignored if Rbind() results in an inbound connection over a SOCKS server. In this scenario the 
socket is logically bound to the SOCKS server IP address coupled with a port selected via SOCKS 
server. If a bind() is performed, then the socket is bound to the local IP address and port number 
specified. 


3. The Rbind() function may be explicitly used, or optionally you can compile your application with 
the __Rbind macro defined when you call the compiler. For example, if you are compiling with a 
Create C Module (CRTCMOD) CL command, specify __Rbind for the DEFINE keyword to cause 
the __Rbind macro to be defined before the compilation starts. Now all bind() calls in the program 
will become Rbind(). See <sys/socket.h> for a definition of the __Rbind macro. 


4. When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the Rbind() API is mapped to 
qso_Rbind98().*& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


@ accept()--Wait for Connection Request and Make Connection 


e bind()--Set Local Address for Socket 


@ connect()--Establish Connection or Destination Address 


@ getsockname()--Retrieve Local Address of Socket 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


read()--Read from Descriptor 


Syntax 


#include <unistd.h> 


ssize_t read(int file_descriptor, 
void *buf, size_t nbyte); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


From the file or socket indicated by file_descriptor, the read() function reads nbyte bytes of input into the 
memory area indicated by buf. If nbyte is zero, read() returns a value of zero without attempting any other 
action. 


If file_descriptor refers to a "regular file" (a stream file that can support positioning the file offset) or any 
other type of file on which the job can do an Iseek() operation, read() begins reading at the file offset 
associated with file_descriptor. A successful read() changes the file offset by the number of bytes read. 


If read() is successful and nbyte is greater than zero, the access time for the file is updated. 
read() is not supported for directories. 


If file_descriptor refers to a descriptor obtained using the open() function with O_TEXTDATA specified, 
the data is read from the file assuming it is in textual form. The maximum number of bytes on a single read 
that can be supported for text data is 2,147,483,408 (2GB - 240) bytes. The data is converted from the code 
page of the file to the code page of the application, job, or system as follows: 


e When reading from a true stream file, any line-formatting characters (such as carriage return, tab, 
and end-of-file) are just converted from one code page to another. 


e When reading from record files that are being used as stream files, end-of-line characters are added 
to the end of the data in each record. 


There are some important considerations when the file is open for text conversion and the CCSIDs involved 
are not strictly single-byte: 


e The read() will return the exact number of bytes requested. For some CCSIDs, this may mean that 
partial characters are returned at the end of the user buffer. In this case, the remainder of the 
character has been read from the file and internally buffered. The next consecutive read() will begin 
with the remainder of the partial character. However, if an Iseek() is performed, the buffered data 
will be discarded. See lseek()--Set File Read/Write Offset for more information. 


e Because of the above consideration and because of the possible expansion or contraction of 
converted data, applications using the O_CCSID flag should avoid assumptions about data size and 
the current file offset. For example, a file might have a physical size of 100 bytes, but after an 
application has read 100 bytes from the file, the current file offset may be 50. In order to read the 
whole file, the application might have to read 200 bytes or more, depending on the CCSIDs 
involved. 


If O_TEXTDATA was not specified on the open(), the data is read from the file without conversion. The 
application is responsible for handling the data. 


In the QSYS.LIB #*and independent ASP QSYS.LIB file systems, {most end-of-file characters are 
symbolic; that is, they are stored outside the member. When reading: 


e If O_TEXTDATA is specified, both symbolic and nonsymbolic end-of-file characters can be seen. 


e If O_TEXTDATA is not specified (binary mode), only nonsymbolic end-of-file characters can be 
seen. 


See the Usage Notes for write()--Write to Descriptor. 


When file_descriptor refers to a socket, the read() function reads from the socket identified by the socket 
descriptor. 


When attempting to read from an empty pipe or FIFO: 
e If no job has the pipe or FIFO open for writing, read() return 0 to indicate end-of-file. 


e If some job has the pipe or FIFO open for writing and O_NONBLOCK was specified, read() will 
fail and errno will be set to [EAGAIN]. 


e If some job has the pipe or FIFO open for writing and O_NONBLOCK was not specified, read() 
will block the calling thread until some data is written or until the pipe or FIFO is closed by all jobs 
that had the pipe or FIFO open for writing. 


Parameters 


file_descriptor 
(Input) The descriptor to be read. 


buf 

(Output) A pointer to a buffer in which the bytes read are placed. 
nbyte 

(Input) The number of bytes to be read. 
Authorities 


No authorization is required. 


Return Value 


value 
read() was successful. The value returned is the number of bytes actually read and placed in buf. 
This number is less than or equal to nbyte. It is less than nbyte only if read() reached the end of the 
file before reading the requested number of bytes. If read() is reading a regular file and encounters 
a part of the file that has not been written (but before the end of the file), read() places bytes 
containing zeros into buf in place of the unwritten bytes. 

-1 


read() was not successful. The errno global variable is set to indicate the error. If the value of nbyte 
is greater than SSIZE_MAX, read() sets errno to [EINVAL]. 


Error Conditions 


If readQ(Q) is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBUSY] 


[EDAMAGE] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations 
to file permissions at the server are not reflected at the client until updates to data that 
is stored locally by the Network File System take place. (Several options on the Add 
Mounted File System (ADDMFS) command determine the time between refresh 
operations of local data.) Access to a remote file may also fail due to different 
mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. 


This may occur if file_descriptor refers to a socket and the socket is using a 
connection-oriented transport service, and a connect() was previously completed. The 
thread, however, does not have the appropriate privileges to the objects that were 
needed to establish a connection. For example, the connect() required the use of an 
APPC device that the thread was not authorized to. 


Operation would have caused the process to be suspended. 


If file_descriptor refers to a pipe or FIFO that has its O_NONBLOCK flag set, this 
error occurs if the read() would have blocked the calling thread. 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or a 
read or write request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or, this read request 
was made to a file that was only open for writing. 

A file ID could not be assigned when linking an object to a directory. 


The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as 
possible. 


Resource busy. 
An attempt was made to use a system resource that is not available at this time. 
A damaged object was encountered. 


A referenced object is damaged. The object cannot be used. 


[EFAULT] 


2[EINTR] 


[EINVAL] 


[EIO] 


[ENOMEM] 


[ENOTAVAIL] 


[ENOTSAFE] 


#[ENXIO] 


[EOVERFLOW] 


#[ERESTART] 


The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not 
valid. 


While attempting to access a parameter passed to this function, the system detected an 
address that is not valid. 


Interrupted function call.“ 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on 
an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


This may occur if file_descriptor refers to a socket that is using a connectionless 
transport service, is not a socket of type SOCK_RAW, and is not bound to an address. 


The file resides in a file system that does not support large files, and the starting 
offset of the file exceeds 2GB minus 2 bytes. 


Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 

Storage allocation request failed. 

A function needed to allocate storage, but no storage is available. 
There is not enough memory to perform the requested function. 
Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the independent 
ASP. 


Function is not allowed in a job that is running with multiple threads. 
No such device or address.*& 


Object is too large to process. 
The object's data size exceeds the limit allowed by this function. 


The file is a regular file, nbyte is greater than 0, the starting offset is before the 
end-of-file, and the starting offset is greater than or equal to 2GB minus 2 bytes. 


A system call was interrupted and may be restarted. 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have 
been deleted at the server. 


[EUNKNOWN] Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, then retry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNABORTED] 


[ECONNREFUSED] 


[ECONNRESET] 


[EINTR] 


[ENOTCONN] 


[ETIMEDOUT] 


[EUNATCH] 


[EWOULDBLOCK] 


Connection ended abnormally. 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent on 
the socket. 


e A protocol error was detected. 


The destination socket refused an attempted connect operation. 


A connection with a remote socket was reset by that socket. 


Interrupted function call. 


Requested operation requires a connection. 


This error code is returned only on sockets that use a connection-oriented 
transport service. 


A remote host did not respond within the timeout period. 


A non-blocking connect() was previously completed that resulted in the 
connection timing out. No connection is established. This error code is returned 
only on sockets that use a connection-oriented transport service. 


The protocol required to support the specified address family is not available at 
this time. 


Operation would have caused the process to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following 


errors: 


[EADDRNOTAVAIL] Address not available. 


[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


[ECONNRESET] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[ENETDOWN] 


[ENETRESET] 


[ENETUNREACH] 


[ESTALE] 


[ETIMEDOUT] 


[EUNATCH] 


Error Messages 


The destination socket refused an attempted connect operation. 

A connection with a remote socket was reset by that socket. 

A remote host is not available. 

A route to the remote host is not available. 

The network is not currently available. 

A socket is connected to a host that is no longer available. 

Cannot reach the destination network. 

File or object handle rejected by server. 

If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


A remote host did not respond within the timeout period. 


The protocol required to support the specified address family is not available at 
this time. 


The following messages may be sent from this function: 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. Error number &1. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
o Where multiple threads exist in the job. 


o The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

wg QNTC 

mw QSYS.LIB 

m Independent ASP QSYS.LIB & 
gw QOPT 


2. QSYS.LIB #and Independent ASP QSYS.LIB “File System Differences 


This function will fail with error code [ENOTSAFE] if the object on which this function is 
operation is a save file and multiple threads exist in the job. 


This function will fail with error code [EIO] if the file specified is a save file and the file does not 
contain complete save file data. 


The file access time for a database member is updated using the normal rules that apply to database 
files. At most, the access time is updated once per day. 


If you previously used the integrated file system interface to manipulate a member that contains an 
end-of-file character, you should avoid using other interfaces (such as the Source Entry Utility or 
database reads and writes) to manipulate the member. If you use other interfaces after using the 
integrated file system interface, the end-of-file information will be lost. 


3. QOPT File System Differences 
The file access time is not updated on a read() operation. 


When reading from files on volumes formatted in Universal Disk Format (UDF), byte locks on the 
range being read are ignored. 


4. Network File System Differences 


Local access to remote files through the Network File System may produce unexpected results due 
to conditions at the server. Once a file is open, subsequent requests to perform operations on the 
file can fail because file attributes are checked at the server on each request. If permissions on the 
file are made more restrictive at the server or the file is unlinked or made unavailable by the server 
for another client, your operation on an open file descriptor will fail when the local Network File 
System receives these updates. The local Network File System also impacts operations that retrieve 
file attributes. Recent changes at the server may not be available at your client yet, and old values 
may be returned from operations. (Several options on the Add Mounted File System (ADDMFS) 
command determine the time between refresh operations of local data.) 


Reading and writing to files with the Network File System relies on byte-range locking to 
guarantee data integrity. To prevent data inconsistency, use the fentl() API to get and release these 
locks. 


5. QFileSvr.400 File System Differences 


The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will 
be received. 


6. For sockets that use a connection-oriented transport service (for example, sockets with a type of 
SOCK_STREAM), a return value of zero indicates one of the following: 


oO The partner program has issued a close() for the socket. 
o The partner program has issued a shutdown() to disable writing to the socket. 
o The connection is broken and the error was returned on a previously issued socket function. 


o A shutdown() to disable reading was previously done on the socket. 


7. The following applies to sockets that use a connectionless transport service (for example, a socket 
with a type of SOCK_DGRAM). 


o. If a connect() has been issued previously, then data can be received only from the address 
specified in the previous connect(). 


o The address from which data is received is discarded, since the read() has no address 
parameter. 


o The entire message must be read in a single read operation. If the size of the message is too 
large to fit in the user supplied buffer, the remaining bytes of the message are discarded. 


o A returned value of zero indicates one of the following: 
m The partner program has sent a NULL message (a datagram with no user data). 
a A shutdown() to disable reading was previously done on the socket. 


m The buffer length specified was zero. 


8. For file systems that do not support large files, read() will return [EINVAL] if the starting offset 
exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that do 
support large files, read() will return [EOVERFLOW] if the starting offset exceeds 2GB minus 2 
bytes and the file was not opened for large file access. 


9. Using this function successfully on the 4*/dev/null or /dev/zero “Kcharacter special file results in a 


return value of zero. In addition, the access time for the file is updated. 


Related Information 


e The <limits.h> file (see Header Files for UNIX-Type Functions) 
e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


@ creat()--Create or Rewrite File 


e dupQ--Duplicate Open File Descriptor 


e dup2(--Duplicate Open File Descriptor to Another Descriptor 


e fcntlQ--Perform File Control Command 


e ioctl)--Perform I/O Control Request 
e@ lseek()--Set File Read/Write Offset 


@ open()--Open File 

@ =pread()--Read from Descriptor with Offset 

@ pread64()--Read from Descriptor with Offset (large file enabled) 
e pwrite()--Write to Descriptor with Offset 

e pwrite64()--Write to Descriptor with Offset (large file enabled) 


e readv()--Read from Descriptor Using Multiple Buffers 


@ recv()--Receive Data 


e recvfrom()--Receive Data 


e recvmsg()--Receive Data or Descriptors or Both 


@ write()--Write to Descriptor 


@ writev(Q--Write to Descriptor Using Multiple Buffers 


Example 


The following example opens a file and reads input: 


#include <stdio.h> 
#include <unistd.h> 
#include <fcntl.h> 


main() { 
int ret, file_descriptor, rc; 
char buf[]="Test text"; 


if ((file_descriptor = creat ("test.output", S_IWUSR))!= 0) 
perror("creat() error"); 
else { 
if (-1l==(rce=write(file_descriptor, buf, sizof(buf)-1))) 
perror("write() error"); 
if (close(file_descriptor) != 0) 
perror("close() error"); 


} 


if ((file_descriptor = open("test.output", O_RDONLY)) < 0) 
perror ("open() error"); 
else { 
ret = read(file_descriptor, buf, sizeof (buf)-1)); 
buf[ret] = 0x00; 
printf ("block read: \n<%s>\", buf); 
if (close(file_descriptor) != 0) 
perror("close() error"); 


if (unlink ("test.output") != 0) 
perror("unlink() error"); 


} 
Output: 


block read: 
<Test text> 


API introduced: V3R1 
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readv()--Read from Descriptor Using Multiple 
Buffers 


Syntax 


#include <sys/types.h> 
#include <sys/uio.h> 


int readv(int descriptor, 
struct iovec *io_vector[], 
int vector_length) 


Threadsafe: Conditional; see Usage Notes. 


The readv() function is used to receive data from a file or socket descriptor. readv() provides a way for data 
to be stored in several different buffers (scatter/gather I/O). 


See read()--Read from Descriptor for more information related to reading from a descriptor. 


Parameters 


descriptor 


(Input) The descriptor to be read. The descriptor refers to a file or a socket. 


io_vector[] 


(I/O) The pointer to an array of type struct iovec. struct iovec contains a sequence of pointers to 
buffers in which the data to be read is stored. The structure pointed to by the io_vector parameter is 
defined in <sys/uio.h>. 


struct iovec { 
void *iov_base; 
size_t iov_len; 


} 


iov_base and iov_len are the only fields in iovec used by sockets. iov_base contains the pointer to a 
buffer and iov_len contains the buffer length. The rest of the fields are reserved. 


vector_length 


(Input) The number of entries in io_vector. 


Authorities 


No authorization is required. 


Return Value 


readv() returns an integer. Possible values are: 


e -! (unsuccessful) 


e n (successful), where n is the number of bytes read. 


Error Conditions 


If readv() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBUSY] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or path. 


If you are accessing a remote file through the Network File System, update operations 
to file permissions at the server are not reflected at the client until updates to data that 
is stored locally by the Network File System take place. (Several options on the Add 
Mounted File System (ADDMFS) command determine the time between refresh 
operations of local data.) Access to a remote file may also fail due to different 
mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. 


This may occur if file_descriptor refers to a socket and the socket is using a 
connection-oriented transport service, and a connect() was previously completed. The 
thread, however, does not have the appropriate privileges to the objects that were 
needed to establish a connection. For example, the connect() required the use of an 
APPC device that the thread was not authorized to. 


Operation would have caused the process to be suspended. 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or a 
read or write request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or, this readv 
request was made to a file that was only open for writing. 

A file ID could not be assigned when linking an object to a directory. 


The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as 
possible. 


Resource busy. 


An attempt was made to use a system resource that is not available at this time. 


[EDAMAGE] A damaged object was encountered. 
A referenced object is damaged. The object cannot be used. 
[EFAULT] The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is not 
valid. 


While attempting to access a parameter passed to this function, the system detected an 
address that is not valid. 


(EINTR] Interrupted function call.*& 


[EINVAL] The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted on 
an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


This may occur if file_descriptor refers to a socket that is using a connectionless 
transport service, is not a socket of type SOCK_RAW, and is not bound to an address. 


The file resides in a file system that does not support large files, and the starting 
offset of the file exceeds 2 GB minus 2 bytes. 


[EIO] Input/output error. 
A physical I/O error occurred. 
A referenced object may be damaged. 
[ENOMEM] Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 
There is not enough memory to perform the requested function. 
[ENOTAVAIL] Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the independent 
ASP. 


[ENOTSAFE] Function is not allowed in a job that is running with multiple threads. 


[EOVERFLOW] Object is too large to process. 
The object's data size exceeds the limit allowed by this function. 


The file is a regular file, nbyte is greater than 0, the starting offset is before the 
end-of-file and is greater than or equal to 2GB minus 2 bytes. 


2}[ERESTART] A system call was interrupted and may be restarted.*& 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may have 
been deleted at the server. 


[EUNKNOWN] Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, then retry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNABORTED] 


[ECONNREFUSED] 


[ECONNRESET] 


[EINTR] 


[ENOTCONN] 


[ETIMEDOUT] 


[EUNATCH] 


[EWOULDBLOCK] 


Connection ended abnormally. 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent on 
the socket. 


e A protocol error was detected. 


The destination socket refused an attempted connect operation. 


A connection with a remote socket was reset by that socket. 


Interrupted function call. 


Requested operation requires a connection. 


This error code is returned only on sockets that use a connection-oriented 
transport service. 


A remote host did not respond within the timeout period. 


A non-blocking connect() was previously completed that resulted in the 
connection timing out. No connection is established. This error code is returned 
only on sockets that use a connection-oriented transport service. 


The protocol required to support the specified address family is not available at 
this time. 


Operation would have caused the process to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following 


errors: 


[EADDRNOTAVAIL] Address not available. 


[ECONNABORTED] 


Connection ended abnormally. 


[ECONNREFUSED] 


[ECONNRESET] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[ENETDOWN] 


[ENETRESET] 


[ENETUNREACH] 


[ESTALE] 


[ETIMEDOUT] 


[EUNATCH] 


Error Messages 


The destination socket refused an attempted connect operation. 

A connection with a remote socket was reset by that socket. 

A remote host is not available. 

A route to the remote host is not available. 

The network is not currently available. 

A socket is connected to a host that is no longer available. 

Cannot reach the destination network. 

File or object handle rejected by server. 

If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


A remote host did not respond within the timeout period. 


The protocol required to support the specified address family is not available at 
this time. 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. Error number &1. 


Usage Notes 
1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 


oO Where multiple threads exist in the job. 


o The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mg QSYS.LIB 

m Independent ASP QSYS.LIB & 
mw QOPT 


2. The io_vector[] parameter is an array of struct iovec structures. When a readv() is issued, the 
system processes the array elements one at a time, starting with io_vector[0]. For each element, 
iov_len bytes of received data are placed in storage pointed to by iov_base. Data is placed in 
storage until all buffers are full, or until there is no more data to receive. Only the storage pointed 
to by iov_base is updated. No change is made to the iov_len fields. To determine the end of the 
data, the application program must use the following: 


o The function return value (the total number of bytes received). 


oO The lengths of the buffers pointed to by iov_base. 


3. For sockets that use a connection-oriented transport service (for example, sockets with a type of 
SOCK_STREAM), a returned value of zero indicates one of the following: 


o The partner program has issued a close() for the socket. 
oO The partner program has issued a shutdown() to disable writing to the socket. 
o The connection is broken and the error was returned on a previously issued socket function. 


oO A shutdown() to disable reading was previously done on the socket. 


4. The following applies to sockets that use a connectionless transport service (for example, a socket 
with a type of SOCK_DGRAM): 


oO If aconnect() has been issued previously, then data can be received only from the address 
specified in the previous connect(). 


o The address from which data is received is discarded, because the readv() has no address 
parameter. 


o The entire message must be read in a single read operation. If the size of the message is too 
large to fit in the user-supplied buffers, the remaining bytes of the message are discarded. 


o Areturned value of zero indicates one of the following: 
m The partner program has sent a NULL message (a datagram with no user data). 


a A shutdown() to disable reading was previously done on the socket. 


m The buffer length specified by the application was zero. 


5. For the file systems that do not support large files, readv() will return [EINVAL] if the starting 
offset exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that 
do support large files, readv() will return [EOVERFLOW] if the starting offset exceeds 2GB minus 
2 bytes and file was not opened for large file access. 


6. QFileSvr.400 File System Differences 


The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will 
be received. 

7. QOPT File System Differences 
When reading from files on volumes formatted in Universal Disk Format (UDF), byte locks on the 
range being read are ignored. 


8. Using this function successfully on the /dev/null #*or /dev/zero *&character special file results in a 
return value of 0. In addition, the access time for the file is updated. 


Related Information 


e The <limits.h> file (see Header Files for UNIX-Type Functions) 
e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


@ creat()--Create or Rewrite File 


e dup(--Duplicate Open File Descriptor 


e@ dup2()--Duplicate Open File Descriptor to Another Descriptor 


e fcntl0--Perform File Control Command 


e ioctl(--Perform I/O Control Request 
@ lseek()--Set File Read/Write Offset 


@ open()--Open File 


e@ read()--Read from Descriptor 


@ recv()--Receive Data 


e recvfrom(--Receive Data 
e@ recvmsg()--Receive Data or Descriptors or Both 


@ write(--Write to Descriptor 


@ writev()--Write to Descriptor Using Multiple Buffers 
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recv()--Receive Data 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int recv(int socket_descriptor, 
char *buffer, 


int buffer_length, 
int flags) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


ssize_t recv(int socket_descriptor, 
void *buffer, 


size_t buffer_length, 
int flags) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


% 


The recv() function is used to receive data through a socket. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


socket_descriptor 


(Input) The socket descriptor that is to be read from. 


buffer 
(Input) The pointer to the buffer in which the data that is to be read is stored. 


buffer_length 
(Input) The length of the buffer. 


flags 
(Input) A flag value that controls the reception of the data. The flags value is either zero, or is 
obtained by performing an OR operation on one or more of the following constants: 
MSG_OOB Receive out-of-band data. Valid only for sockets with an address family of 
AF_INET 2% or AF_INET6 * and type SOCK_STREAM. 
MSG_PEEK Obtain a copy of the message without removing the message from the 
socket. 
2*MSG_WAITALL Wait for a full request or an error.*& 
Authorities 


No authorization is required. 


Return Value 


recv() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is the number of bytes received. 


Error Conditions 


When recv() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 


The socket pointed to by the socket_descriptor parameter is using a 
connection-oriented transport service, and a connect() was previously completed. 
The process, however, does not have the appropriate privileges to the objects that 
were needed to establish a connection. For example, the connect() required the 
use of an APPC device that the process was not authorized to. 


[EBADF] 


[ECONNABORTED] 


[ECONNREFUSED] 


[ECONNRESET] 


[EFAULT] 


[EINTR] 


[EINVAL] 


[EIO] 


[ENOBUFS] 


[ENOTCONN] 


[ENOTSOCK] 


Descriptor not valid. 


Connection ended abnormally. 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent on 
the socket. 


e A protocol error was detected. 


The destination socket refused an attempted connect operation. 


A connection with a remote socket was reset by that socket. 


Bad address. 


The system detected an address which was not valid while attempting to access 
the buffer parameter. 


Interrupted function call. 


Parameter not valid. 
This error code indicates one of the following: 


e The buffer_length parameter specifies a negative value. 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but no OOB data was available to be received. 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
and the socket option SO_OOBINLINE has been set. 


e The socket_descriptor parameter points to a socket that is using a 
connectionless transport service, is not a socket of type SOCK_RAW, 
and is not bound to an address. 


Input/output error. 


There is not enough buffer space for the requested operation. 


Requested operation requires a connection. 


This error code is returned only on sockets that use a connection-oriented 
transport service. 


The specified descriptor does not reference a socket. 


[EOPNOTSUPP] 


[ETIMEDOUT] 


[EUNATCH] 


[EUNKNOWN] 


[EWOULDBLOCK] 


Operation not supported. 


This error code indicates one of the following: 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a connectionless socket. 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a socket that does not have 
an address family of AF_INET#* or AF_INET6 &. 


A remote host did not respond within the timeout period. 

A nonblocking connect() call was previously done that resulted in the connection 
establishment timing out. No connection is established. This error code is 
returned only on sockets that use a connection-oriented transport service. 

The protocol required to support the specified address family is not available at 
this time. 


Unknown system state. 


Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. For sockets that use a connection-oriented transport service (for example, sockets with a type of 
SOCK_STREAM), a returned value of zero indicates one of the following: 


o The partner program has issued a close() for the socket. 


oO The partner program has issued a shutdown() to disable writing to the socket. 


o The connection is broken and the error was returned on a previously issued socket function. 


oO A shutdown() to disable reading was previously done on the socket. 


2. The following applies to sockets that use a connectionless transport service (for example, a socket 
with a type of SOCK_DGRAM): 


oO If aconnect() has been issued previously, then data can be received only from the address 
specified in the previous connect(). 


oO The address from which data is received is discarded, since the recv() has no address 
parameter. 


o The entire message must be read in a single read operation. If the size of the message is too 
large to fit in the user supplied buffer, the remaining bytes of the message are discarded. 


o A returned value of zero indicates one of the following: 


m The partner program has sent a NULL message (a datagram with no user data), 
a A shutdown() to disable reading was previously done on the socket. 


m The buffer length specified was zero. 


3. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the recv() API is mapped to 
qso_recv98().*& 


Related Information 


e@ = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e fentlO--Perform File Control Command 


e ioctlQ--Perform I/O Control Request 


e@ recvfrom()--Receive Data 


e@ recvmsg()--Receive Data or Descriptors or Both 
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recvfrom()--Receive Data 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int recvfrom(int socket_descriptor, 
char *buffer, 
int buffer_length, 
int flags, 
struct sockaddr *from_address, 
int *address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


ssize_t recvfrom(int socket_descriptor, 
void *buffer, 
size_t buffer_length, 
int flags, 
struct sockaddr *from_address, 
socklen_t *address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


« 


The recvfrom() function is used to receive data through a connected or unconnected socket. 


»> There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and syntax. The other uses 
syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 
compatible interface with the _XOPEN_ SOURCE macro. & 


Parameters 


socket_descriptor 
(Input) The socket descriptor that is to be read from. 


buffer 
(Input) The pointer to the buffer in which the data that is to be read is stored. 


buffer_length 
(Input) The length of the buffer. 


int flags 


(Input) A flag value that controls the reception of the data. The flags value is either zero, or is obtained by performing an 
OR operation on one or more of the following constants: 


MSG_OOB Receive out-of-band data. Valid only for sockets with an address family of AF_INET# or 
AF_INET6& and type SOCK_STREAM. 


MSG_PEEK Obtain a copy of the message without removing the message from the socket. 


2%MSG_WAITALL Wait for a full request or an error.& 


from_address 


(Output) A pointer to a buffer of type struct sockaddr that contains the address from which the message was received. 
The structure sockaddr is defined in <sys/socket.h>. 


» The BSD 4:3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


}; 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address family to which the 
address belongs, and sa_data is the address whose format is dependent on the address family. 


» Note: See the usage notes about using different address families with sockaddr_storage. 


« 


address_length 


(Input/output) This parameter is a value-result field. The caller passes a pointer to the length of the from_address 
parameter. On return from the call, address_length will contain the actual length of the address. 


Authorities 


An errno of EACCES is returned when the socket pointed to by the socket_descriptor field is address family AF_INET and a 
nonblocking connect was attempted previously and was not successful. The nonblocking connect was not successful because the 
thread did not have authority to the associated APPC device. The thread performing the nonblocking connect must have retrieve, 
insert, delete, and update authority to the APPC device. 


Return Value 


recvfrom() returns an integer. Possible values are: 
e -1 (unsuccessful) 


e n (successful), where n is the number of bytes received. 


Error Conditions 


When recvfrom() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 
The socket pointed to by the socket_descriptor parameter is using a connection-oriented transport 
service, and a connect() was previously completed. The process, however, does not have the 
appropriate privileges to the objects that were needed to establish a connection. For example, the 


connect() required the use of an APPC device that the process was not authorized to. 


[EBADF] Descriptor not valid. 


[ECONNABORTED] Connection ended abnormally. 


This error code indicates that the transport provider ended the connection abnormally because of one of 
the following: 


e The retransmission limit has been reached for data that was being sent on the socket. 


e A protocol error was detected. 


[ECONNREFUSED] | The destination socket refused an attempted connect operation. 
[ECONNRESET] A connection with a remote socket was reset by that socket. 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the buffer, 
from_address, or address_length parameter. 


[EINTR] Interrupted function call. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The buffer_length parameter specifies a negative value. 


e The flags parameter specifies a value that includes the MSG_OOB flag, but no OOB data was 
available to be received. 


e The flags parameter specifies a value that includes the MSG_OOB flag, and the socket option 
SO_OOBINLINE has been set. 


e The socket_descriptor parameter points to a socket that is using a connectionless transport 
service, is not a socket of type SOCK_RAW, and is not bound to an address. 


[EIO] Input/output error. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTCONN] Requested operation requires a connection. 
This error code is returned only on sockets that use a connection-oriented transport service. 


[ENOTSOCK] The specified descriptor does not reference a socket. 


[EOPNOTSUPP] Operation not supported. 


This error code indicates one of the following: 


e The flags parameter specifies a value that includes the MSG_OOB flag, but the 
socket_descriptor parameter points to a connectionless socket. 


e The flags parameter specifies a value that includes the MSG_OOB flag, but the 
socket_descriptor parameter points to a socket that does not have an address family of 
AF_INET# or AF_INET6&. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 


A non-blocking connect() was previously issued that resulted in the connection establishment timing 
out. No connection is established. This error code is returned only on sockets that use a 
connection-oriented transport service. 


[EUNATCH] The protocol required to support the specified address family is not available at this time. 
[EUNKNOWN] Unknown system state. 


[EWOULDBLOCK] Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 
1. For sockets that use a connection-oriented transport service (for example, sockets with a type of SOCK_STREAM), a 
returned value of zero indicates one of the following: 
oO. The partner program has issued a close() for the socket. 
o The partner program has issued a shutdown() to disable writing to the socket. 
o The connection is broken and the error was returned on a previously issued socket function. 
oO. A shutdown() to disable reading was previously done on the socket. 


2. If the socket is using a connection-oriented transport service, the from_address and address_length parameters are 
ignored. 


3. The following applies to sockets that use a connectionless transport service (for example, a socket with a type of 
SOCK_DGRAM): 


o. If a connect() has been issued previously, then data can be received only from the address specified in the 
previous connect(). 


o If the from_address parameter is set to NULL or address_length specifies a value of zero, the address from which 
data is received is discarded by the system. 


o If the length of the address to be returned exceeds the length of the from_address parameter, the returned address 
is truncated. 


o The structure sockaddr is a generic structure used for any address family but it is only 16 bytes long. The 
actual address returned for some address families may be much larger. You should declare storage for the address 
with the structure sockaddr_storage. This structure is large enough and aligned for any protocol-specific 
structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the 
sockaddr_storage will always align with the family field of any protocol-specific structure. 


The BSD 4.3 structure is: 


#define _SS_ MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE —- sizeof (sa_family_t) ) 

#define _SS_PAD2SIZE (_SS_MAXSIZE —- (sizeof (sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 


sa_family_t ss_family; 

char _ss_padl[_SS_PADI1SIZE]; 
char* _ss_align; 

char _ss_pad2[_SS_PAD2SI1ZE]; 


he 
The BSD 4.4/UNIX 98 compatible structure is: 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - (sizeof (uint8_t) + 

sizeof (sa_family_t))) 

#define _SS_PAD2SIZE (_SS_MAXSIZE —- (sizeof (uint8_t) + sizeof(sa_family_t)+ 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


struct sockaddr_storage { 


uint8_t ss_len; 
sa_family_t ss_family; 
char _ss_padl[_SS_PADI1SIZE]; 
char* _ss_align; 
char _ss_pad2[_SS_PAD2SI1ZE]; 
hi 
« 
o If the socket is using an address family of AF_UNIX, the address (which is a path name) is returned in the default 
coded character set identifier (CCSID) currently in effect for the job. 
o If the socket is using an address family of AF_UNIX_CCSID, the output structure sockaddr_unc defines the 


format and coded character set identifier (CCSID) of the address (which is a path name). 


oO The entire message must be read in a single read operation. If the size of the message is too large to fit in the user 
supplied buffer, the remaining bytes of the message are discarded. 


o A returned value of zero indicates one of the following: 


m The partner program has sent a NULL message (a datagram with no user data). 


a A shutdown() to disable reading was previously done on the socket. 


m The buffer length specified was zero. 


4. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to 
the value 520 or greater, the recvfrom() API is mapped to gso_recvfrom98().& 


Related Information 


e »_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface& 


e fcntlQ--Perform File Control Command 


e ioctl()--Perform I/O Control Request 


e@ recv()--Receive Data 


e@ recvmsg()--Receive Data or Descriptors or Both 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


recvmsg()--Receive Data or Descriptors or Both 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int recvmsg(int socket_descriptor, 


struct msghdr *message_structure, 
int flags) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


ssize_t recvmsg(int socket_descriptor, 


struct msghdr *message_structure, 
int flags) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


= 


The recvmsg() function is used to receive data or descriptors or both through a connected or unconnected 
socket. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. *& 


Parameters 


socket_descriptor 


(Input) The socket descriptor that is to be read from. 


message_structure 
(I/O) The pointer to the message structure that contains the following: 


oO The address from which the message was received 
o The vector array in which the data received is stored 


o #The ancillary data/access rights list in which the received descriptors are stored 


The structure pointed to by the message_structure parameter is defined in <sys/socket.h>. 


The BSD 4.3 structure is: 


struct msghdr { 


caddr_t msg_name; 

int msg_namelen; 
struct iovec *msg_iov; 

Eni msg_iovlen; 
caddr_t msg_accrights; 
aigehel msg_accrightslen; 


hi 
The BSD 4.4/UNIX 98 compatible structure is: 


struct msghdr { 


void *msg_name; 
socklen_t msg_namelen; 
struct iovec *msg_iov; 

int msg_iovlen; 
void *msg_control; 
socklen_t msg_controllen; 
int msg_flags; 


}; 
€ 


The msg_name and msg_namelen fields contain the address and address length to which the 
message is sent. For further information on the structure of socket addresses, see Sockets 


Programming in the iSeries Information Center. If the msg_name field is set to a NULL pointer, the 
address information is not returned. 


The msg_iov and msg_iovlen fields are for scatter/gather I/O. 


= The BSD 4.3 structure uses the msg_accrights and msg_accrightslen fields to pass descriptors. 
The msg_accrights field is a list of zero or more descriptors, and msg_accrightslen is the total 
length (in bytes) of the descriptor list. 


The BSD 4.4/UNIX 98 compatible structure uses the msg_control and msg_controllen fields to 
pass descriptors. The msg_control field is a pointer to ancillary data (of length msg_controllen) 
with the form: 


struct cmsghdr { 
socklen_t cmsg_len; 
int cmsg_level; 
int cmsg_type; 
}; 


The cmsg_len field is the total length including this header. cmsg_level is the originating protocol. 
cmsg_len is the protocol-specific type. To pass descriptors, cmsg_level is set to SOL_SOCKET and 
cmsg_type is set to SCM_RIGHTS. The rest of the buffer is a list of zero or more descriptors. 


Macros are provided for navigating these structures. 


Oo CMSG_DATA(cmsg) If the argument is a pointer to a cmsghdr structure, this macro returns 
an unsigned character pointer to the data array associated with the cmsghdr structure. 


Oo CMSG_NXTHDR(mhdr,cmsg) If the first argument is a pointer to a msghdr structure and 
the second argument is a pointer to a cmsghdr structure in the ancillary data, pointed to by 
the msg_control field of that msghdr structure, this macro returns a pointer to the next 
cmsghadr structure, or a null pointer if this structure is the last cmsghdr in the ancillary data. 


oO CMSG_FIRSTHDR(mhdr) If the argument is a pointer to a msghdr structure, this macro 
returns a pointer to the first cmsghdr structure in the ancillary data associated with this 
msghdr structure, or a null pointer if there is no ancillary data associated with the msghdr 
structure. 

The BSD 4.4/UNIX 98 compatible structure has the msg_flags for message level flags including: 

Oo MSG_TRUNC Message data was truncated 

oO MSG_CTRUNC Ancillary data was truncated. 

Oo MSG_EOR End of record (if supported by the protocol). 

oO MSG_OOB Out-of-band data. 


= 
flags 
(Input) A flag value that controls the reception of the data. The flags value is either zero, or is 
obtained by performing an OR operation on one or more of the following constants: 
MSG_OOB Receive out-of-band data. Valid only for sockets with an address family of 
AF_INET#* or AF_INET6% and type SOCK_STREAM. 
MSG_PEEK Obtain a copy of the message without removing the message from the 
socket. 
2*MSG_WAITALL Wait for a full request or an error.*& 
Authorities 


e Anerrno of EACCES is returned when the socket pointed to by the socket_descriptor field is 


address family AF_INET and a nonblocking connect was attempted previously and was not 
successful. The nonblocking connect was not successful because the thread did not have authority 
to the associated APPC device. The thread performing the nonblocking connect must have retrieve, 
insert, delete, and update authority to the APPC device. 


e If this thread is receiving socket descriptors, it must have *ALLOBJ special authority or must be 
running under the same user profile as the thread that sent the descriptors using sendmsg. If both of 
these conditions are not true, the descriptors are reclaimed by the machine and an errno of 
EACCES is returned. 


Return Value 


recvmsg() returns an integer. Possible values are: 


e@ -1 (unsuccessful) 


e n (successful), where n is the number of bytes received. 


Error Conditions 


When recvmsg() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 


The socket pointed to by the socket_descriptor parameter is using a 
connection-oriented transport service, and a connect() was previously completed. 
The process, however, does not have the appropriate privileges to the objects that 
were needed to establish a connection. For example, the connect() required the 
use of an APPC device that the process was not authorized to. 


If the msg_accrights and msg_accrightslen fields # (or the BSD 4.4/UNIX 98 
compatible fields msg_control and msg_controllen) «£ were specified, this error 
indicates that this job does not have the appropriate privileges required to receive 
the descriptor. When this occurs, the descriptor is reclaimed by the system and 
the resource that it represented is closed. 


[EBADF] Descriptor not valid. 


[ECONNABORTED] Connection ended abnormally. 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent on 
the socket. 


e A protocol error was detected. 


[ECONNREFUSED] | The destination socket refused an attempted connect operation. 
[ECONNRESET] A connection with a remote socket was reset by that socket. 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access 
the message_structure parameter or a field within the structure pointed to by the 
message_structure parameter. 


[EINTR] 


[EINVAL] 


[EIO] 


[EMFILE] 


[EMSGSIZE] 


[ENOBUFS] 


[ENOTCONN] 


[ENOTSOCK] 


Interrupted function call. 


Parameter not valid. 


This error code indicates one of the following: 


The msg_iovien field or the iov_len field in a iovec structure specifies a 
negative value. 


The flags parameter specifies a value that includes the MSG_OOB flag, 
but no OOB data was available to be received. 


The flags parameter specifies a value that includes the MSG_OOB flag, 
and the socket option SO_OOBINLINE has been set. 


The socket_descriptor parameter points to a socket that is using a 
connectionless transport service, is not a socket of type SOCK_RAW, 
and is not bound to an address. 


The msg_accrightslen field % (or the BSD 4.4/UNIX 98 compatible 
field msg_controllen) *& in the msghdr structure specifies a negative 
value # or is not large enough to hold at least one descriptor when 
msg_accrights & (or the BSD 4.4/UNIX 98 compatible fields 
msg_control) *& was specified. 


Input/output error. 


Too many descriptions for this process. 


Message size out of range. 


The msg_iovlen field specifies a value that is greater than [MSG_MAXIOVLEN] 
(defined in <sys/socket.h>). 


There is not enough buffer space for the requested operation. 


Requested operation requires a connection. 


This error code is returned only on sockets that use a connection-oriented 
transport service. 


The specified descriptor does not reference a socket. 


[EOPNOTSUPP] Operation not supported. 


This error code indicates one of the following: 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a connectionless socket. 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a socket that does not have 
an address family of AF_INET#* or AF_INET6%. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 


A non-blocking connect() was previously issued that resulted in the connection 
establishment timing out. No connection is established. This error code is 
returned only on sockets that use a connection-oriented transport service. 


[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 
[EUNKNOWN] Unknown system state. 


[EWOULDBLOCK] _ Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. The following applies to sockets that use a connection-oriented transport service (for example, 
sockets with a type of SOCK_STREAM), 


o The msg_name and msg_namelen fields in the structure pointed to by the 
message_structure parameter are ignored. 


o Areturned value of zero indicates one of the following: 


m The partner program has issued a close() for the socket. 


m The partner program has issued a shutdown() to disable writing to the socket. 


m The connection is broken and the error was returned on a previously issued socket 
function. 


a A shutdown() to disable reading was previously done on the socket. 


2. The following applies to sockets that use a connectionless transport service (for example, a socket 
with a type of SOCK_DGRAM): 


oO If aconnect() has been issued previously, then data can be received only from the address 
specified in the previous connect(). 


o If the msg_name field is set to NULL or msg_namelen field specifies a value of zero, the 
address from which data is received is discarded. 


o If the length of the address to be returned exceeds the length specified by the msg_namelen 
field, the returned address is truncated. 


o. If the socket is using an address family of AF_UNIX, the address (which is a path name) is 
returned in the default coded character set identifier (CCSID) currently in effect for the job. 


o If the socket is using an address family of AF_UNIX_CCSID, the output structure 
sockaddr_unc defines the format and coded character set identifier (CCSID) of the address 
(which is a path name). 


o The entire message must be read in a single read operation. If the size of the message is too 
large to fit in the user supplied buffer, the remaining bytes of the message are discarded. 


o Areturned value of zero indicates one of the following: 


m The partner program has sent a NULL message (a datagram with no user data). 
m A shutdown() to disable reading was previously done on the socket. 


m The buffer length specified was zero. 


3. The passing of descriptors is only supported over sockets that have an address family of AF_UNIX 
or AF_UNIX_CCSID. The msg_accrightslen and the msg_accrights fields % (or the BSD 
4.4/UNIX 98 compatible fields msg_control and msg_controllen) *& are ignored if the socket has 
any other address family. The value of msg_accrightslen # (or the BSD 4.4/UNIX 98 compatible 
field msg_controllen) *& should be checked to determine if a descriptor has been returned. When 
you use sendmsg() and recvmsg() to pass descriptors, the target job must be running with either of 
the following: 


o The same user profile as the source job (in essence, passing the descriptor to yourself) 
o *ALLOBS special authority 


If the target job closes the receiving end of the UNIX domain socket while a descriptor is in transit, 
the descriptor is reclaimed by the system, and the resource that it represented is closed. For files 
and directories, the ability to pass descriptors using sendmsg() and recvmsg() is only supported for 
objects in the root and QOpenSys file systems. 


Note: The recvmsg() API will not block unless a data buffer is specified. 


4. recvmsg() accepts a pointer to an array of iovec structures in the msghdr structure. The msg_iovlen 
field is used to determine the number of elements in the array (the number of iovec structures 
specified). When recvmsg() is issued, the system processes the array elements one at a time, 
starting with the first structure. For each element of the array (for each structure), iov_len bytes of 
received data are placed in storage pointed to by iov_base. Data is placed in storage until all buffers 
are full, or until there is no more data to receive. Only the memory pointed to by iov_base is 
updated. No change is made to the iov_len fields. To determine the end of the data, the application 
program must use the following: 


o The function return value (the total number of bytes received). 


oO The lengths of the buffers pointed to by iov_base. 


5. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the recvmsg() API is mapped to 
gso_recvmsg98().%& 


Related Information 


e For additional information and sample programs on how to use sendmsg() and recvmsg() to pass 
descriptors between system jobs, see Sockets Programming in the iSeries Information Center. 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface*& 


e fcntl(--Perform File Control Command 


e ioctlQ--Perform I/O Control Request 


e@ givedescriptor()--Pass Descriptor Access to Another Job 


@ recv()--Receive Data 


e recvfrom()--Receive Data 


e takedescriptor()--Receive Socket Access from Another Job 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


rexec()--lssue a Command on a Remote Host 


Syntax 


#include <arpa/rexec.h> 


int rexec(char **host, 
int port, 
char *user, 
char *password, 
char *command, 
int *errorDescriptor); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The rexec() function is used to open a connection to a remote host and send a user ID, password, and 
command to the remote host. The remote host verifies that the user ID and password are valid. The 
command is issued after the user ID and password are validated. 


Parameters 


host (Input) 


A pointer to a character string that identifies the name of a remote host. 


port (Input) 


The well-known Internet port to use for the connection. A pointer to the structure containing the 
necessary port can be obtained by issuing the following call: 


getservbyname ("exec", "tcp"); 
The port returned by getservbyname() is the port on which the remote host is listening for incoming 
rexec() connections. 
user (Input) 


A character string that identifies a valid user on the remote host. 


password (Input) 


A character string that identifies the password for the user on the remote host. Specify a value of 
NULL if password security is not active on the remote host. 


command (Input) 


A character string that identifies the command to be issued on the remote host. 


errorDescriptor (Input/Output) 


One of the following values: 


non-NULL A second connection is set up and that a descriptor for it is placed in the 
errorDescriptor parameter. This connection provides standard error results of the 
remote command. This information also includes remote authorization failure if 
rexec() is unsuccessful. 


NULL The standard error results of the remote command are the same as the standard 
output return value. 


Return Value 


rexec() returns an integer. Possible values are: 
Non-negative 


(successful) A socket to the remote command is returned and can be used to receive results of 
running the command on the remote host. 


o If errorDescriptor is non-NULL, standard error results of running the command on the 
remote host can be received by using the errorDescriptor. 


o If errorDescriptor is NULL, standard error results of running the command on the remote 
host can be received with the standard output results by using the return value from rexec(). 


[=i] 
(unsuccessful) Refer to errno for a description of the failure. 


o If errno is 0 and errorDescriptor is NULL, the host does not exist or remote authorization 
failed. 


o If errno is 0 and errorDescriptor is -1, the host does not exist. 


o If errno is 0 and errorDescriptor is non-negative, remote authorization failed. 


Authorities 


No authorization is required. 


Error Conditions 
When the rexec() API fails, errno can be set to one of following: 


[ECONNABORTED] Connection ended abnormally. 


[ECONNREFUSED] The destination socket refused an attempted connect operation. 


This error occurs when the rexec server on the remote system is not active. 


[ECONNRESET] 


[EFAULT] 


[EHOSTUNREACH] 
[EINTR] 

[EINVAL] 
[EMFILE] 

[ENFILE] 

[EPIPE] 


[ETIMEDOUT] 


[EUNATCH] 


[EUNKNOWN] 


Usage Notes 


A connection with a remote socket was reset by that socket. 


Bad address. 


System detected an address which was not valid while attempting to access the 
address parameters. 

A route to the remote host is not available. 

Interrupted function call. 

Parameter not valid. 

Too many descriptors for this process. 

Too many descriptors in system. 

Broken pipe. 

A remote host did not respond within the timeout period. 

This error code is returned when connection establishment times out. No 


connection is established. A possible cause may be that the partner application is 
bound, but the partner application has not yet issued a listen(). 


The protocol required to support address family AF_INET, is not available at 
this time. 


Unknown system state. 


e The password does not get encrypted while sent to the rexec server. 


e Any results of the command received by the caller of rexec() are not converted from CCSID 819. 
Conversion from ASCII ccsid 819 to the CCSID of the process or thread is the caller's 


responsibility. 


e If aremote authorization failure occurs, the return value will be -1 and if errorDescriptor is 
non-null a message indicating the authorization failure can be received with the socket descriptor 
from errorDescriptor. 


e Any socket descriptor returned to the caller of rexec() must be explicitly closed by the caller. 


e The user, password, and command will be translated from the job ccsid to ASCII ccsid 819 to be 


sent to the remote host. 


e Issuing rexec() to a remote host that is configured to set up a SOCKSified connection is not 
supported. 


Related Information 


@ rexec_r()--Issue a Command on a Remote Host 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example shows how rexec() is used: 


#include <stdio.h> 
#include <stdlib.h> 
#include <sys/types.h> 
#include <sys/socket.h> 
#include <qtqiconv.h> 
#include <arpa/rexec.h> 
#include <errno.h> 


#define BufLen 256 


void main () 
{ 
int sd = -l, rc; 
int responseLen = BufLen; 
int outbytesleft = BufLen; 
int bytesRead, saveBytesRead; 
struct servent serv_ent; 
struct servent_data serv_ent_data; 
char inbuf [BufLen]; 
char outbuf[BufLen]; 


char *inbufPtr = (char *) inbuf; 

char *outbufPtr = (char *) outbuf; 

iconv_t cd; 

QtqCode_T toCode = {0,0,0,0,0,0}; /* Convert to job CCSID */ 


QtqCode_T fromCode = {819,0,0,1,0,0}; /* ASCII CCSID */ 
char *host; 


char remoteHost[256] = "remoteHost"; 
char user[32] = "userName"; 

char password[32] = "myPassword",; 
char cmd[256] = "commandToRun"; 


int *errordesc = NULL; 


/* Must zero this out before call or results will be unpredictable. */ 
memset (&serv_ent_data.serve_control_blk, 0x00, sizeof(struct 
netdb_control_block)); 


/* retrieve the rexec server port number */ 
re = getservbyname_r("exec", "tcp", &serv_ent, &serv_ent_data); 
FE (ee << O') 


printf ("getservbyname_r() failed with errno = %d\n",errno); 
host = remoteHost; 
errno = 0; 


/* Issue the rexec API */ 
sd = rexec(&host, serv_ent.s_port, user, password, cmd, errordesc); 
if (sd == -1) /* check if rexec() failed */ 
{ 
if (errno) 
printf ("rexec() failed with errno = %d\n",errno) ; 
else 
printf ("Either the host does not exist or remote authentication 
failed.\n"); 
} 
else /* rexec() was successful */ 
{ 
bytesRead = recv(sd, inbuf, responseLen, 0); 
if (bytesRead > 0) 
{ 
saveBytesRead = bytesRead; 
inbuf [bytesRead-1] = 0; /* Null terminate */ 
/* translate from ASCII to EBCDIC */ 
cd = QtgqIconvOpen(&toCode, &fromCode) ; 
iconv (cd, 
(unsigned char **)&inbufPtr, 
(unsigned int *) &ébytesRead, 
(unsigned char **) &outbufPtr, 
(unsigned int *) &é0utbytesleft) ; 
iconv_close(cd); 
outbufPtr -= saveBytesRead; /* Reset the buffer pointers */ 
printf ("Ss\n", outbufPtr) ; 
} 
else if (bytesRead == 0) 
printf ("The remote host closed the connection.\n"); 


else 
printf ("recv() failed with errno = %d\n",errno); 
} 
if (sd != -1) 
close(sd); /* close the connection. */ 
return; 


API introduced: V5R1 
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rexec_r()--lssue a Command on a Remote Host 


Syntax 


#include <arpa/rexec.h> 


int rexec_r(char **host, 
int port, 
char *user, 
char *password, 
char *command, 
int *errorDescriptor, 
struct hostent_data *hostEntData); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The rexec_r() function is used to open a connection to a remote host and send a user ID, password, and 
command to the remote host. The remote host verifies that the user ID and password are valid. The 
command will be issued after the user ID and password are validated. 


Parameters 


host (Input) 


A pointer to a character string that identifies the name of a remote host. 


port (Input) 


The well-known Internet port to use for the connection. A pointer to the structure that contains the 
necessary port can be obtained by issuing the following call: 


struct servent servEnt; 

struct servent_data servEntData; 

memset (&servEntData.serve_control_blk, 0x00, sizeof (struct 
netdb_control_block) ); 

getservbyname_r("exec", "tcp", &servEnt, &servEntData) ; 


The port returned by getservbyname_r() is the port that the remote host is listening on for incoming 
rexec_r() connections. 
user (Input) 


A character string that identifies a valid user on the remote host. 


password (Input) 


A character string that identifies the password for the user on the remote host. Specify a value of 
NULL if password security is not active on the remote host. 


command (Input) 


A character string that identifies the command to be issued on the remote host. 


errorDescriptor (Input/Output) 


One of the following values: 


non-NULL A second connection is set up, and a descriptor for it is placed in the 
errorDescriptor parameter. This connection provides standard error results of the 
remote command. This information will also include remote authorization failure if 
rexec() is unsuccessful. 


NULL The standard error results of the remote command is the same as the standard 
output return value. 


hostEntData (Input/Output) 


A pointer to the hostent_data structure, which is used to pass and preserve results between function 
calls. rexec_r() performs a gethostbyname_r() and each thread needs its own host data. The field 
host_control_block in the hostent_data structure must be initialized to hexadecimal zeros before its 
initial use. If compatibility with other platforms is required, then the entire hostent_data structure 
must be initialized to hexadecimal zeros before its initial use. The Hostent_data structure is defined 
in <netdb.h>>. 


Return Value 


rexec_r() returns an integer. Possible values are: 
Non-negative 


(successful) A socket to the remote command is returned and can be used to receive results of 
running the command on the remote host. 


o If errorDescriptor is non-NULL, standard error results of running the command on the 
remote host can be received by using the errorDescriptor. 


o If errorDescriptor is NULL, standard error results of running the command on the remote 
host can be received along with the standard output results by using the return value from 
rexec_r(). 


[-1] 
(unsuccessful) Refer to errno for a description of the failure. 


o If errno is 0 and errorDescriptor is NULL, the host does not exist or remote authorization 
failed. 


o If errno is 0 and errorDescriptor is -1, the host does not exist. 


o If errno is 0 and errorDescriptor is Non-negative, remote authorization failed. 


Authorities 


No authorization is required. 


Error Conditions 


When the rexec_r() API fails, errno can be set to one of following: 


[ECONNABORTED] 


[ECONNREFUSED] 


[ECONNRESET] 


[EFAULT] 


[EHOSTUNREACH] 


[EINTR] 


[EINVAL] 


[EMFILE] 


[ENFILE] 


[EPIPE] 


[ETIMEDOUT] 


[EUNATCH] 


[EUNKNOWN] 


Connection ended abnormally. 


The destination socket refused an attempted connect operation. 
This error occurs when the rexec server on the remote system is not active. 


A connection with a remote socket was reset by that socket. 


Bad address. 


System detected an address which was not valid while attempting to access the 
address parameters. 


A route to the remote host is not available. 


Interrupted function call. 


Parameter not valid. 


This error code occurs when the hostEntData structure has not been initialized to 
hexadecimal zeros. For corrective action, see the description for structure 
hostent_data. 


Too many descriptors for this process. 


Too many descriptors in system. 


Broken pipe. 


A remote host did not respond within the timeout period. 


This error code is returned when connection establishment times out. No 
connection is established. A possible cause may be that the partner application is 
bound, but the partner application has not yet issued a listen(). 


The protocol required to support address family AF_INET,, is not available at 
this time. 


Unknown system state. 


Usage Notes 
e The password does not get encrypted while sent to the rexec server. 


e Any results of the command received by the caller of rexec_r() are not converted from CCSID 819. 
Conversion from ASCII ccsid 819 to the CCSID of the process or thread is the caller's 
responsibility. 


e If a remote authorization failure occurs, the return value will be -1 and if errorDescriptor is 
non-null a message indicating the authorization failure can be received with the socket descriptor 
from errorDescriptor. 


e Any socket descriptor returned to the caller of rexec_r() must be explicitly closed by the caller. 


e The user, password, and command will be translated from the job ccsid to ASCII ccsid 819 to be 
sent to the remote host. 


e Issuing rexec_r() to a remote host that is configured to set up a SOCKSified connection is not 


supported. 


Related Information 


@ rexec()--Issue a Command on a Remote Host 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example shows how rexec_r() is used: 


#include <stdio.h> 
#include <stdlib.h> 
#include <sys/types.h> 
#include <sys/socket.h> 
#include <qtqiconv.h> 
#include <arpa/rexec.h> 
#include <errno.h> 


#define BufLen 256 


void main() 
{ 
int sd = -l, rc; 
int responseLen = BufLen; 
int outbytesleft = BufLen; 
int bytesRead, saveBytesRead; 


struct hostent_data host_ent_data; 
struct servent serv_ent; 

struct servent_data serv_ent_data; 
char inbuf [BufLen]; 

char outbuf[BufLen]; 


char *inbufPtr = (char *)inbuf; 

char *outbufPtr = (char *) outbuf; 

iconv_t cd; 

QtqCode_T toCode = {0,0,0,0,0,0}; /* Convert to job CCSID */ 


QtqCode_T fromCode = {819,0,0,1,0,0}; /* ASCII CCSID */ 
char *host; 


char remoteHost[256] = "remoteHost"; 
char user[32] = "userName"; 

char password[32] = "myPassword",; 
char cmd[256] = "commandToRun"; 


int *errordesc = NULL; 


/* Must zero this out before call or results will be unpredictable. */ 
memset (&serv_ent_data.serve_control_blk, 0x00, sizeof(struct 
netdb_control_block) ); 


/* retrieve the rexec server port number */ 
re = getservbyname_r("exec", "tcp", &serv_ent, &sServ_ent_data); 
if (re < 0) 

printf ("getservbyname_r() failed with errno = %$d\n",errno); 


/* must zero this out before call or results will be unpredictable. */ 
memset ((void *) &host_ent_data.host_control_blk, 0x00, sizeof (struct 
netdb_control_block) ); 
host = remoteHost; 
errno = 0; 


/* issue the rexec_r api */ 


sd = rexec_r(&host, serv_ent.s_port, user, password, cmd, errordesc, 
&host_ent_data); 
if (sd == -1) /* check if rexec_r() failed */ 


{ 
if (errno) 
printf ("rexec_r() failed with errno = %$d\n",errno) ; 
else 
printf ("Either the host does not exist or remote authentication 
failed.\n"); 
} 
else /* rexec_r() was successful */ 
{ 
bytesRead = recv(sd, inbuf, responseLen, 0); 
if (bytesRead > 0) 
{ 
saveBytesRead = bytesRead; 
inbuf [bytesRead-1] = 0; /* Null terminate */ 
/* translate from ASCII to EBCDIC */ 
cd = QtgqIconvOpen(&toCode, &fromCode) ; 
iconv (cd, 
(unsigned char **) &inbufPtr, 
(unsigned int *) &ébytesRead, 
(unsigned char **) &outbufPtr, 
(unsigned int *)éo0utbytesleft) ; 


iconv_close(cd); 


outbufPtr -= saveBytesRead; /* Reset the buffer pointers 


printf ("Ss\n",outbufPtr) ; 


} 
else if (bytesRead == 0) 
printf ("The remote host closed the connection.\n"); 


else 
printf ("recv() failed with errno = %d\n",errno); 
} 
if (sd != -1) 
close(sd); /* close the connection. */ 
return; 
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rexec_r_ts64()--lssue a Command on a Remote 
Host 


Syntax 


#include <arpa/rexec.h> 


int rexec_r_ts64(char * __ptr64 * __ptr64 host, 
int port, 
char * _ ptr64 user, 
char * _ ptr64 password, 
char * _ _ptr64 command, 
int * _ ptr64 errorDescriptor, 
struct hostent_data * __ ptr64hostEntData); 


Service Program Name: QSOSRVTS 


Default Public Authority: *USE 


Threadsafe: Yes 


The rexec_r_ts64() function is used to open a connection to a remote host and send a user ID, password, 
and command to the remote host. The remote host verifies that the user ID and password are valid. The 
command is issued after the user ID and password are validated. rexec_r_ts64() differs from rexec_r() in 
that rexec_r_ts64() accepts 8-byte teraspace pointers. 


For a discussion of the parameters, authorities required, return values, and other related information, see 
rexec_r()--Issue a Command on a Remote Host. 


Usage Notes 


All of the usage notes for rexec_r()--Issue a Command on a Remote Host apply to rexec_r_ts64(). 
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rexec_ts64()--lssue a Command on a Remote 
Host 


Syntax 


#include <arpa/rexec.h> 


int rexec_ts64(char * __ptr64 * __ ptr64 host, 
int port, 
char * __ptr64 user, 
char * __ptr64 password, 
char * __ptr64 command, 
int * __ptr64 errorDescriptor); 


Service Program Name: QSOSRVTS 


Default Public Authority: *USE 


Threadsafe: Yes 


The rexec_ts64() function is used to open a connection to a remote host and send a user ID, password, and 
command to the remote host. The remote host verifies that the user ID and password are valid. The 
command is issued after the user ID and password are validated. rexec_ts64() differs from rexec() in that 
rexec_ts64() accepts 8-byte teraspace pointers. 


For a discussion of the parameters, authorities required, return values, and other related information, see 
rexec()--Issue a Command on a Remote Host. 


Usage Notes 


All of the usage notes for rexec()--Issue a Command on a Remote Host apply to rexec_ts64(). 
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select()--Wait for Events on Multiple Sockets 


Syntax 


#include <sys/types.h> 
#include <sys/time.h> 


int select (int max_descriptor, 
fd_set *read_set, 
fd_set *write_set, 
fd_set *exception_set, 
struct timeval *wait_time) 


Service Program Name: QPOLLIB1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The select() function is used to enable an application to multiplex I/O. By using select(), an application with 
multiple interactive I/O sources avoids blocking on one I/O stream while the other stream is ready. Thus, 
for example, an application that receives inputs from two distinct communication endpoints (using sockets) 
can use select() to sleep until input is available from either of the sources. When input is available, the 
application wakes up and receives an indication as to which descriptor is ready for reading. 


The application identifies descriptors to be checked for read, write, and exception status and specifies a 
timeout value. If any of the specified descriptors is ready for the specified event (read, write, or exception), 
select() returns, indicating which descriptors are ready. Otherwise, the process waits until one of the 
specified events occur or the wait times out. 


Parameters 


max_descriptor 


(Input) Descriptors are numbered starting at zero, so the max_descriptor parameter must specify a 
value that is one greater than the largest descriptor number that is to be tested. 


read_set 


(I/O) A pointer to a set of descriptors that should be checked to see if they are ready for reading. 
This parameter is a value-result field. Each descriptor to be tested should be added to the set by 
issuing a FD_SET() macro. If no descriptor is to be tested for reading, read_set should be NULL 
(or point to an empty set). On return from the call, only those descriptors that are ready to be read 
are in the set. FD_ISSET( should be used to test for membership of a descriptor in the set. 


write_set 


(I/O) A pointer to a set of descriptors that should be checked to see if they are ready for writing. 
This parameter is a value-result field. Each descriptor to be tested should be added to the set by 
issuing a FD_SET(Q) macro. If no descriptor is to be tested for writing, write_set should be NULL 
(or point to an empty set). On return from the call, only those descriptors that are ready to be 


written are in the set. FD_ISSET( should be used to test for membership of a descriptor in the set. 


exception_set 


(I/O) A pointer to a set of descriptors that should be checked for pending exception events. This 
parameter is a value-result field. Each descriptor to be tested should be added to the set by issuing a 
FD_SETQ macro. If no descriptor is to be tested for exceptions, exception_set should be NULL (or 
point to an empty set). On return from the call, only those descriptors that have an exception event 
are in the set. FD_ISSETQ should be used to test for membership of a descriptor in the set. 


wait_time 


(Input) A pointer to a structure which specifies the maximum time to wait for at least one of the 
selection criteria to be met. A time to wait of 0 is allowed; this returns immediately with the current 
status of the sockets. The parameter may be specified even if NO descriptors are specified (select() 
is being used as a timer). If wait_time is NULL, select() blocks indefinitely. The structure pointed 
to by the wait_time parameter is defined in <sys/time.h>. 


Return Value 


select() returns an integer. Possible values are: 


e -! (unsuccessful) 
e 0 (if the time limit expires) 


e n (total number of descriptors in all sets that met selection criteria) 


Note: The timeval structure (pointed to by wait_time) is unchanged. 


Error Conditions 


When select() fails, errno can be set to one of the following: 


[EBADF] Descriptor not valid. 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
read_set, write_set, exception_set, or wait_time parameter. 


[EINTR] Interrupted function call. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The max_descriptor parameter specifies a negative value or a value greater 
than [FD_SETSIZE]. 


e The wait_time parameter specifies a time value which was not valid. 


[EIO] Input/output error. 


[EUNKNOWN] Unknown system state. 


Error Messages 


CPE3418E Possible APAR condition or hardware failure. 

CPF3CF2 E — Error(s) occurred during running of &1 API. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
CPFA081E Unable to set return value or error code. 


CPFAOD4 E_ File system error occurred. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
Oo Where multiple threads exist in the job. 


oO. The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 
mw User-defined 
gw QNTC 

gw QSYS.LIB 
mw QOPT 


2. An application program must include the header file <sys/types.h> to use select(). The header file 
contains the type and macro definitions needed to use select(). The maximum number of 
descriptors that can be selected is defined by FD_SETSIZE. The following macros can be used to 


manipulate descriptor sets: 


o FD_ZERO(fd_set *p) removes all descriptors from the set specified by p. 
o FD_CLR(int n, fd_set *p) removes descriptor n from the set specified by p. 
o FD_SET<(int n, fd_set *p) adds descriptor n to the set specified by p. 


o FD_ISSET«(nt n, fd_set *p) returns a nonzero value if descriptor n is returned in the set 
specified by p; otherwise, a zero value is returned. 


Note: Values of type fd_set should only be manipulated by the macros supplied in the 
<sys/types.h> header file. 


3. A descriptor can be returned in the set specified by read_set to indicate one of the following: 


o An error event exists on the descriptor. 


o Aconnection request is pending on a socket descriptor. This technique can be used to wait 
for connections on multiple socket descriptors. When a listening socket is returned in the 
set specified by read_set, an application can then issue an accept() call to accept the 
connection. 


o No data can be read from the underlying instance represented by the descriptor. For 
example, a socket descriptor for which a shutdown() call has been done to disable the 
reception of data. 


4. A descriptor can be returned in the set specified by write_set to indicate one of the following: 


o Completion of a non-blocking connect() call on a socket descriptor. This allows an 
application to set a socket descriptor to nonblocking (with fcentl() or ioctl()), issue a 
connect() and receive [EINPROGRESS], and then use select() to verify that the connection 
has completed. 


o No data can be written to the underlying instance represented by the descriptor (for 
example, a socket descriptor for which a shutdown() has been done to disable the sending 
of data). 


o When a write() can be successfully issued without blocking (or, for nonblocking, so it does 
not return [EWOULDBLOCK]). 


5. A socket descriptor is returned in the set specified by exception_set to indicate that out-of-band 
data has arrived at the socket. This is only supported for connection-oriented sockets with an 
address family of AF_INET#* or AF_INET6%. 
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send()--Send Data 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int send(int socket_descriptor, 
char *buffer, 


int buffer_length, 
int flags) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


ssize_t send(int socket_descriptor, 
const void *buffer, 


size_t buffer_length, 
int flags) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


4 


The send() function is used to send data through a connected socket. 


# There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


socket_descriptor 
(Input) The socket descriptor that is to be written to. 


buffer 
(Input) The pointer to the buffer in which the data that is to be written is stored. 


buffer_length 
(Input) The length of the buffer. 


flags 
(Input) A flag value that controls the transmission of the data. The flags value is either zero, or is 
obtained by performing an OR operation on the following constants: 
2*MSG_EOR Terminate a record, if supported by the protocol. 
MSG_OOB Send data as out-of-band data. Valid only for sockets with an address 
family of AF_INET#* or AF_INET6% and type SOCK_STREAM. 
MSG_DONTROUTE Bypass routing. Valid only for sockets with address family of AF_INET. 
It is ignored for other address families. 
Authorities 


No authorization is required. 


Return Value 


send() returns an integer. Possible values are: 


e -! (unsuccessful) 


e n (successful), where n is the number of bytes sent. 


Error Conditions 


When send() fails, errno can be set to one of the following: 


[EACCES] 


[EBADF] 


[ECONNREFUSED] 


[EDESTADDRREQ] 


[EFAULT] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[EINTR] 


[EINVAL] 


[EIO] 


[EMSGSIZE] 


Permission denied. 


This error code indicates one of the following: 


e Destination address specified a broadcast address and the socket option 
SO_BROADCAST was not set (with a setsockopt()). 


e The process does not have the appropriate privileges to the destination 
address. This error code can only be returned on a socket with a type of 
SOCK_DGRAM and an address family of AF_INET. 


Descriptor not valid. 


The destination socket refused an attempted connect operation. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Operation requires destination address. 


A destination address has not been associated with the socket pointed to by the 
socket_descriptor parameter. This error code can only be returned on sockets that 
use a connectionless transport service. 


Bad address. 


The system detected an address which was not valid while attempting to access 
the buffer parameter. 


A remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


A route to the remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Interrupted function call. 


Parameter not valid. 
The buffer_length parameter specifies a negative value. 


Input/output error. 


Message size out of range. 


The data to be sent could not be sent atomically because the size specified by 
buffer_length is too large. 


[ENETDOWN] 


[ENETUNREACH] 


[ENOBUFS] 


[ENOTCONN] 


[ENOTSOCK] 


[EOPNOTSUPP] 


[EPIPE] 


[EUNATCH] 


[EUNKNOWN] 


[EWOULDBLOCK] 


The network is not currently available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Cannot reach the destination network. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


There is not enough buffer space for the requested operation. 


Requested operation requires a connection. 


This error code can only be returned on sockets that use a connection-oriented 
transport service. 


The specified descriptor does not reference a socket. 


Operation not supported. 


This error code indicates one of the following: 
e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a connectionless socket. 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a socket that does not have 
an address family of AF_INET#* or AF_INET6%. 


Broken pipe. 


The protocol required to support the specified address family is not available at 
this time. 


Unknown system state. 


Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. send() only works with sockets on which a connect() has been issued, since it does not allow the 
caller to specify a destination address. 


2. To broadcast on an AF_INET socket, the socket option SO._BROADCAST must be set (with a 
setsockopt()). 


3. When using a connection-oriented transport service, all errors except [EUNATCH] and 
[EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following 
occurs: 


o Aconnection that is in progress is unsuccessful. 
o An established connection is broken. 
To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation 


(for example, read()). 


4. #When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the send() API is mapped to 
qso_send98().%& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 
e fcntl(--Perform File Control Command 


e ioctl()--Perform I/O Control Request 


e sendto()--Send Data 


e sendmsg()--Send Data or Descriptors or Both 


@ write(--Write to Descriptor 


@ writev()--Write to Descriptor Using Multiple Buffers 
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sendmsg()--Send Data or Descriptors or Both 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int sendmsg(int socket_descriptor, 


struct msghdr *message_structure, 
int flags) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


ssize_t sendmsg(int socket_descriptor, 


const struct msghdr *message_structure, 
int flags) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


= 


The sendmsg() function is used to send data or descriptors or both through a connected or unconnected 
socket. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


socket_descriptor 


(Input) The socket descriptor that is to be written to. 


message_structure 
(I/O) The pointer to the message structure that contains the following: 


oO The address to which the message is to be sent 
o The vector array in which the data to be sent is stored 


© #The ancillary data/access rights list in which the sent descriptors are stored. 


The structure pointed to by the message_structure parameter is defined in <sys/socket.h>. 


The BSD 4.3 structure is: 


struct msghdr { 


caddr_t msg_name; 

int msg_namelen; 
struct iovec *msg_iov; 

Eni msg_iovlen; 
caddr_t msg_accrights; 
aigehel msg_accrightslen; 


hi 
The BSD 4.4/UNIX 98 compatible structure is: 


struct msghdr { 


void *msg_name; 
socklen_t msg_namelen; 
struct iovec *msg_iov; 

int msg_iovlen; 
void *msg_control; 
socklen_t msg_controllen; 
int msg_flags; 


}; 
€ 


The msg_name and msg_namelen fields contain the address and address length to which the 
message is sent. For further information on the structure of socket addresses, see Sockets 


Programming in the iSeries Information Center. If the msg_name field is set to a NULL pointer, the 
address information is not returned. 


The msg_iov and msg_iovlen fields are for scatter/gather I/O. 


= The BSD 4.3 structure uses the msg_accrights and msg_accrightslen fields to pass descriptors. 
The msg_accrights field is a list of zero or more descriptors, and msg_accrightslen is the total 
length (in bytes) of the descriptor list. 


The BSD 4.4/UNIX 98 compatible structure uses the msg_control and msg_controllen fields to 
pass descriptors. The msg_control field is a pointer to ancillary data (of length msg_controllen) 
with the form: 


struct cmsghdr { 
socklen_t cmsg_len; 
int cmsg_level; 
int cmsg_type; 
}; 


The cmsg_len field is the total length including this header. cmsg_level is the originating protocol. 
cmsg_len is the protocol-specific type. To pass descriptors, cmsg_level is set to SOL_SOCKET and 
cmsg_type is set to SCM_RIGHTS. The rest of the buffer is a list of zero or more descriptors. 


Macros are provided for navigating these structures. 


Oo CMSG_DATA(cmsg) If the argument is a pointer to a cmsghdr structure, this macro returns 
an unsigned character pointer to the data array associated with the cmsghdr structure. 


Oo CMSG_NXTHDR(mhdr,cmsg) If the first argument is a pointer to a msghdr structure and 
the second argument is a pointer to a cmsghdr structure in the ancillary data, pointed to by 
the msg_control field of that msghdr structure, this macro returns a pointer to the next 
cmsghar structure, or a null pointer if this structure is the last cmsghdr in the ancillary data. 


oO CMSG_FIRSTHDR(mhdr) If the argument is a pointer to a msghdr structure, this macro 
returns a pointer to the first cmsghdr structure in the ancillary data associated with this 
msghdr structure, or a null pointer if there is no ancillary data associated with the msghdr 
structure. 


The BSD 4.4/UNIX 98 msg_flags field is ignored for sendmsg(). & 


flags 
(Input) A flag value that controls the transmission of the data. The flags value is either zero, or is 
obtained by performing an OR operation on one or more of the following constants: 
2*MSG_EOR Terminate a record, if supported by the protocol. 
MSG_OOB Send data as out-of-band data. Valid only for sockets with an address 
family of AF_INET#* or AF_INET6*S and type SOCK_STREAM. 
MSG_DONTROUTE Bypass routing. Valid only for sockets with address family of AF_INET. 
It is ignored for other address families. 
Authorities 


When the address family of the socket identified by the socket_descriptor is AF_INET and is running IP 
over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. When the 
thread does not have this level of authority, an errno of EACCES is returned. 


Return Value 


sendmsg() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is the number of bytes sent. 


Error Conditions 


When sendmsg() fails, errno can be set to one of the following: 


[EACCES] 


[EADDRNOTAVAIL] 


[EBADF] 


[ECONNREFUSED] 


[EDESTADDRREQ] 


[EFAULT] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[EINTR] 


Permission denied. 
The process does not have the appropriate privileges to the destination address. 
Address not available. 


A socket with an address family of AF_INET 2 or AF_INET6*& is using a 
connectionless transport service, the socket was not bound. The system tried to 
bind the socket but could not because a port was not available. 


Descriptor not valid. 


The destination socket refused an attempted connect operation. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Operation requires destination address. 


A destination address has not been associated with the socket pointed to by the 
socket_descriptor parameter and a destination address was not set in the msghdr 
structure (pointed to by the message_structure parameter). This error code can 
only be returned on sockets that use a connectionless transport service. 


Bad address. 


The system detected an address which was not valid while attempting to access 
the message_structure parameter or a field within the structure pointed to by the 
message_structure parameter. 


A remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


A route to the remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Interrupted function call. 


[EINVAL] 


[EIO] 


Parameter not valid. 


This error code indicates one of the following: 


The msg_iovien field or the iov_len field in a iovec structure specifies a 
negative value. The fields are contained in the msghdr structure (pointed 
to by the message_structure parameter). 


The msg_namelen field in the msghdr structure (pointed to by the 
message_structure parameter) specifies a length that is not valid for the 
address family. 


The msg_accrightslen field 3 (or the BSD 4.4/UNIX 98 compatible 
field msg_controllen) % in the msghdr structure (pointed to by the 
message_structure parameter) specifies a negative value #* or is not 
large enough to hold at least one descriptor when msg_accrights 2 (or 
the BSD 4.4/UNIX 98 compatible field msg_control) *& was specified. 
& 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the CCSID specified in sunc_gq/g in the 
sockaddr_unc structure (pointed to by /ocal_address) cannot be 
converted to the current default CCSID for integrated file system path 
names. 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and there was an incomplete character or shift state 
sequence at the end of sunc_path in the sockaddr_unc structure 
(pointed to by local_address). 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the sockaddr_unc structure (pointed to by 
local_address) was not valid: 


o The sunc_format was not set to SOQ.UNC_DEFAULT or 
SO_UNC_USE_QLG. 


o The sunc_zero was not initialized to zeros. 


oO The sunc_format field was set to SO_UNC_USE_QLG and the 
sunc_qlg structure was not valid: 


m The path type was less than 0 or greater than 3. 


m The path length was less than 0 or out of bounds. For 
example, a single-byte path name was greater than 126 
bytes or a double-byte path name was greater than 252 
bytes. 


m A reserved field was not initialized to zeros. 


Input/output error. 


[EISCONN] 


[ELOOP] 


[EMSGSIZE] 


[ENAMETOOLONG] 


[ENETDOWN] 


[ENETUNREACH] 


[ENOBUFS] 
[ENOENT] 


[ENOSYS] 


[ENOTCONN] 


[ENOTDIR] 


A connection has already been established. 


A destination address was set, but the socket pointed to by the socket_descriptor 
parameter already has a destination address associated with it. 


A loop exists in symbolic links encountered during pathname resolution. 


This error code refers to the destination address, and can only be returned by 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


Message size out of range. 


This error code indicates one of the following: 


e The data to be sent could not be sent atomically because the total size of 
the data to be sent is too large. 


e The msg_iovlen field in the msghdr structure (pointed to by the 
message_structure parameter) specifies a value that is greater than 
[MSG_MAXIOVLEN] (defined in <sys/socket.h>). 


File name too long. 


This error code refers to the destination address, and can only be returned by 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


The network is not currently available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Cannot reach the destination network. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


There is not enough buffer space for the requested operation. 
No such file or directory. 


This error code refers to the destination address, and can only be returned by 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


Function not implemented. 


This error code refers to the destination address, and can only be returned by 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


Requested operation requires a connection. 


This error code can only be returned on sockets that use a connection-oriented 
transport service. 


Not a directory. 


This error code refers to the destination address, and can only be returned by 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


[ENOTSOCK] The specified descriptor does not reference a socket. 


[EOPNOTSUPP] Operation not supported. 


This error code indicates one of the following: 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a connectionless socket. 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a socket that does not have 
an address family of AF_IN ET#* or AF_INET6*. 


e The msg_accrights and msg_accrightslen # (or the BSD 4.4/UNIX 98 
compatible fields msg_control and msg_controllen) * were specified 
and the underlying instance represented by the descriptor does not 
support the passing of access rights. 


[EPIPE] Broken pipe. 

[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 

[EUNKNOWN] Unknown system state. 


[EWOULDBLOCK] _ Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. The passing of descriptors is only supported over sockets that have an address family of AF_UNIX 
or AF_UNIX_CCSID. The msg_accrightslen and the msg_accrights fields % (or the BSD 
4.4/UNIX 98 compatible fields msg_control and msg_controllen) *& are ignored if the socket has 
any other address family. When you use sendmsg() and recvmsg() to pass descriptors, the target job 
must be running with either of the following: 


oO The same user profile as the source job (in essence, passing the descriptor to yourself) 
o *ALLOBSJ special authority 


If the target job closes the receiving end of the UNIX domain socket while a descriptor is in transit, 
the descriptor is reclaimed by the system, and the resource that it represented is closed. For files 
and directories, the ability to pass descriptors using sendmsg() and recvmsg() is only supported for 
objects in the root and QOpenSys file systems. 


. sendmsg() is an atomic operation in that it produces one packet of data each time the call is issued 
on a connectionless socket. For example, a sendmsg() to a datagram socket will result in a single 
datagram. 


. A destination address cannot be specified if the socket pointed to by the socket_descriptor 
parameter already has a destination address associated with it. To not specify an address, users 
must set the msg_name field to NULL or set the msg_namelen field to zero. (Not specifying an 
address by setting the msg_namelen field to zero is an IBM extension.) 


Note: The msg_name and msg_namelen fields are ignored if the socket is using a 
connection-oriented transport service. 


. If the socket is using a connectionless transport device, the socket is not bound to an address, and 
the socket type is SOCK_DGRAM, the system automatically selects an address (INADDR_ANY#* 
or in6addr_any*& and an available port number) and binds it to the socket before sending the data. 


. To broadcast on an AF_INET socket, the socket option SO_.BROADCAST must be set (with a 
setsockopt()). 


. When using a connection-oriented transport service, all errors except [EUNATCH] and 
[EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following 
occurs: 


o Aconnection that is in progress is unsuccessful. 


o Anestablished connection is broken. 


To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation 
(for example, read()). 


. If the socket is using an address family of AF_UNIX, the destination address (which is a path 
name) is assumed to be in the default coded character set identifier (CCSID) currently in effect for 
the job. For AF_UNIX_CCSID, the destination address is assumed to be in the format and coded 
character set identifier (CCSID) specified in the sockaddr_unc. 


. For AF_INET sockets over SNA, type SOCK_DGRAM, if a datagram can not be delivered, no 
errors are returned. (As an example, a datagram might not be delivered if there is no datagram 
application at the remote host listening at the requested port.) 


. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the sendmsg() API is mapped to 
gso_sendmsg98().%& 


Related Information 


e For additional information and sample programs on how to use sendmsg() and recvmsg() to pass 
descriptors between iSeries jobs, see Socket Programming in the iSeries Information Center. 


e *_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface** 
e fcntl()--Perform File Control Command 


e ioctl()--Perform I/O Control Request 


e@ givedescriptor()--Pass Descriptor Access to Another Job 


e send()--Send Data 


e sendto(--Send Data 


e takedescriptor()--Receive Socket Access from Another Job 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


sendto()--Send Data 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int sendto(int socket_descriptor, 
char *buffer, 
int buffer_length, 
int flags, 
struct sockaddr *destination_address, 
int address_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


ssize_t sendto(int socket_descriptor, 
const void *buffer, 
size_t buffer_length, 
int flags, 
const struct sockaddr *destination_address, 
socklen_t address_length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


% 


The sendto() function is used to send data through a connected or unconnected socket. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_ SOURCE macro. * 


Parameters 


socket_descriptor 


(Input) The socket descriptor that is to be written to. 


buffer 
(Input) The pointer to the buffer in which the data that is to be written is stored. 


buffer_length 
(Input) The length of the buffer. 


flags 


(Input) A flag value that controls the transmission of the data. The flags value is either zero, or is 
obtained by performing an OR operation on one or more of the following constants: 


2*MSG_EOR Terminate a record, if supported by the protocol. 


MSG_OOB Send data as out-of-band data. Valid only for sockets with an address 
family of AF_INET#* or AF_INET6*S and type SOCK_STREAM. 


MSG_DONTROUTE Bypass routing. Valid only for sockets with address family of AF_INET. 
It is ignored for other address families. 


destination_address 


(Input) A pointer to a buffer of type struct sockaddr that contains the destination address to which 
the data is to be sent. The structure sockaddr is defined in <sys/socket.h>. 


#* The BSD 4.3 structure is: 


struct sockaddr { 
u_short sa_family; 
char sa_data[14]; 
}; 


The BSD 4.4/UNIX 98 compatible structure is: 


typedef uchar sa_family_t; 


struct sockaddr { 


uint8_t sa_len; 
sa_family_t sa_family; 
char sa_data[14]; 


La 


The BSD 4.4 sa_len field is the length of the address. & The sa_family field identifies the address 
family to which the address belongs, and sa_data is the address whose format is dependent on the 
address family. 


address_length 


(Input) The length of the destination_address. 


Authorities 


When the address family of the socket identified by the socket_descriptor is AF_INET and is running IP 
over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. When the 
thread does not have this level of authority, an errno of EACCES is returned. 


Return Value 


sendto() returns an integer. Possible values are: 


e -! (unsuccessful) 


e n (successful), where n is the number of bytes sent. 


Error Conditions 


When sendto() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 
The process does not have the appropriate privileges to the destination address. 
[EADDRNOTAVAIL] Address not available. 


A socket with an address family of AF_INET # or AF_INET6%, is using a 
connectionless transport service, and the socket was not bound. The system tried 
to bind the socket but could not because a port was not available. 


[EBADF] Descriptor not valid. 


[ECONNREFUSED] _ The destination socket refused an attempted connect operation. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


[EDESTADDRREQ] Operation requires destination address. 


A destination address has not been associated with the socket pointed to by the 
socket_descriptor parameter and a destination address was not passed in as an 
argument on the sendto(). This error code can only be returned on sockets that 
use a connectionless transport service. 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access 
the buffer or destination_address parameter. 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[EINTR] 


[EINVAL] 


A remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


A route to the remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Interrupted function call. 


Parameter not valid. 


This error code indicates one of the following: 


The buffer_length parameter specifies a negative value. 


The socket is using a connectionless transport service and the 
address_length parameter specifies a length that is not valid for the 
address family. 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the CCSID specified in sunc_gqlg in the 
sockaddr_unc structure (pointed to by /ocal_address) cannot be 
converted to the current default CCSID for integrated file system path 
names. 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and there was an incomplete character or shift state 
sequence at the end of sunc_path in the sockaddr_unc structure 
(pointed to by local_address). 


The socket_descriptor points to a socket with an address family of 
AF_UNIX_CCSID, and the sockaddr_unc structure (pointed to by 
local_address) was not valid: 


o The sunc_format was not set to SO.UNC_DEFAULT or 
SO_UNC_USE_QLG. 


o The sunc_zero was not initialized to zeros. 


oO The sunc_format field was set to SO_UNC_USE_QLG and the 
sunc_qlg structure was not valid: 


m The path type was less than 0 or greater than 3. 


m The path length was less than 0 or out of bounds. For 
example, a single-byte path name was greater than 126 
bytes or a double-byte path name was greater than 252 
bytes. 


m A reserved field was not initialized to zeros. 


[EIO] Input/output error. 


[EISCONN] A connection has already been established. 


A destination address was set, but the socket pointed to by the socket_descriptor 
parameter already has a destination address associated with it. 


[ELOOP] A loop exists in symbolic links encountered during pathname resolution. 


This error code refers to the destination address, and can only be returned on 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


[EMSGSIZE] Message size out of range. 


The data to be sent could not be sent atomically because the total size of the data 
to be sent is too large. 


[ENAMETOOLONG] | File name too long. 


This error code refers to the destination address, and can only be returned on 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


[ENETDOWN] The network is not currently available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


[ENETUNREACH] Cannot reach the destination network. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOENT] No such file or directory. 


This error code refers to the destination address, and can only be returned on 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


[ENOSYS] Function not implemented. 


This error code refers to the destination address, and can only be returned on 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


[ENOTCONN] Requested operation requires a connection. 


This error code can only be returned on sockets that use a connection-oriented 
transport service. 


[ENOTDIR] Not a directory. 


This error code refers to the destination address, and can only be returned on 
sockets that use the AF_UNIX or AF_UNIX_CCSID address family. 


[ENOTSOCK] The specified descriptor does not reference a socket. 


[EOPNOTSUPP] Operation not supported. 


This error code indicates one of the following: 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a connectionless socket. 


e The flags parameter specifies a value that includes the MSG_OOB flag, 
but the socket_descriptor parameter points to a socket that does not have 
an address family of AF_INET#* or AF_INET6%. 


[EPIPE] Broken pipe. 


[EPROTOTYPE] The socket type or protocols are not compatible. 


This error code is only returned on sockets that use the AF_UNIX or the 
AF_UNIX_CCSID address family. 


[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 
[EUNKNOWN] Unknown system state. 


[EWOULDBLOCK] _ Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. A destination address cannot be specified if the socket pointed to by the socket_descriptor 
parameter already has a destination address associated with it. To not specify an address, users 
must set the destination_address field to NULL or set the address_length field to zero. (Not 
specifying an address by setting the address_length field to zero is an IBM extension.) 


Note: The destination_address and address_length fields are ignored if the socket is using a 
connection-oriented transport service. 


2. If the socket is using a connectionless transport device, the socket is not bound to an address, and 


the socket type is SOCK_DGRAM, the system automatically selects an address (INADDR_ANY#* 
or in6addr_any*& and an available port number) and binds it to the socket before sending the data. 


3. To broadcast on an AF_INET socket, the socket option SO._BROADCAST must be set (with a 
setsockopt()). 


4. When using a connection-oriented transport service, all errors except [EUNATCH] and 
[EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following 
occurs: 


o Aconnection that is in progress is unsuccessful. 


o An established connection is broken. 


To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation 
(for example, read()). 


5. If the socket is using an address family of AF_UNIX, the destination address (which is a path 
name) is assumed to be in the default coded character set identifier (CCSID) currently in effect for 
the job. For AF_UNIX_CCSID, the destination address is assumed to be in the format and coded 
character set identifier (CCSID) specified in the sockaddr_unc. 


6. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the sendto() API is mapped to 
gso_sendto98().*& 


Related Information 


e@ = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e fcentlO--Perform File Control Command 


e ioctl(--Perform I/O Control Request 


e@ send()--Send Data 


e sendmsg()--Send Data or Descriptors or Both 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


send_file()--Send a File over a Socket 
Connection 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int send_file(int *socket_descriptor, 
struct sf_parms *sf_struct, 
int flags) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The send_file() function is used to send the contents of an open file over an existing socket connection. 
The send_file() API is a combination of the IFS read() and the sockets send() and close() APIs. Socket 


applications that transmit a file over a socket connection can, under certain circumstances, obtain improved 
performance by using send_file(). 


Parameters 


socket_descriptor 
(Input/Output) A pointer to the socket descriptor that is to be written to. 


sf_struct 
(Input/Output) A pointer to the send_file structure that contains the following: 
o The header buffer and length 


oO The file descriptor, the offset into the file, the file size, and number of bytes to send from 
the file 


o The trailer buffer and length 


o The number of bytes of data that were sent 


The structure pointed to by the sf_struct parameter is defined in <sys/socket.h>. 


struct sf_parms 


{ 


void *header_data; 


flags 


size_t header_length; 


int file_descriptor; 
size t file_size; 
Off AE file_offset; 


ssize_t file_bytes; 


void *trailer_data; 
size_t trailer_length; 


size t bytes_sent; 


} 
header_data 


(Input/Output) A pointer to a buffer that contains data to be sent before the file data is sent. 


header_length 
(Input/Output) The length in bytes of header_data. 


file_descriptor 


(Input) The file descriptor for a file that has been opened for read access. This is the 
descriptor for the file that contains the data to be transmitted. This field is ignored if the 
file_bytes field is set to 0. 


file_size 


(Output) The size in bytes of the file associated with file_descriptor. 


file_offset 


(Input/Output) The byte offset into the file from which to start sending data. Specify a 
value of 0 to start sending data from the start of the file. If a negative value is passed in, 
send_file() API will return with -1 and the errno will be set to EINVAL. 


file_bytes 


(Input/Output) The number of bytes from the file to be transmitted. Set the file_bytes field 
to -1 to transmit all of the data from the file_offset position in the file to the end of the file. 
If the file_bytes field is set to 0, no data from the file will be transmitted. 


trailer_data 


(Input/Output) A pointer to a buffer that contains data to be sent after the file data is sent. 


trailer_length 
(Input/Output) The length in bytes of trailer_data. 


bytes_sent 
(Output) The number of bytes that have been successfully sent. 


(Input) A flag value that controls what is done with the socket connection after the data has been 


transmitted. The flags value is either zero or it is one of the following constants: 


SF_CLOSE After the header_data, file data, and trailer_data have been successfully sent, the 
connection and the socket descriptor are closed. The descriptor that is pointed to 
by the socket_descriptor parameter is set to -1 before the send_file() API returns to 
the application. 


SF_REUSE After the header_data, file data, and trailer_data have been successfully sent, the 
connection is closed. If socket reuse is supported, the descriptor that is pointed to 
by the socket_descriptor parameter is reset. If socket reuse is not supported, the 
descriptor that is pointed to by the socket_descriptor parameter is closed and set to 
-1. 


Authorities 


No authorization is required. 


Return Value 


send_file() returns an integer. Possible values are: 
e -1 (unsuccessful call) Check errno for additional information 
e 0 (successful call) All of the data has been successfully sent 


e 1 (interrupted call) The command was interrupted while sending data 


Error Conditions 


When send_file() fails, errno can be set to one of the following: 
[EACCES] Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. A thread does not have access to the specified file, directory, 
component, or path. 


If you are accessing a remote file through the Network File System, update 
operations to file permissions at the server are not reflected at the client until updates 
to data that is stored locally by the Network File System takes place. (Several 
options on the Add Mounted File System (ADDMFS) command determine the time 
between refresh operations of local data.) Access to a remote file may also fail due 
to different mappings of user [Ds (UID) or group IDs (GID) on the local and remote 
systems. 


[EBADF] 


[ECONVERT] 


[EFAULT] 


[EINTR] 


[EINVAL] 


[EIO] 


[ENOBUFS] 


[ENOTCONN] 


[ENOTSAFE] 


[ENOTSOCK] 


Descriptor not valid. 


This error code indicates one of the following: 


e The descriptor pointed to by the socket_descriptor parameter is not a valid 
socket descriptor. 


e The file_descriptor parameter is not valid for this operation. The specified 
descriptor is incorrect, does not refer to an open file, or refers to a file that 
was only open for writing. 


Conversion error. 


Bad address. 


The system detected an address that was not valid while attempting to access the 
socket_descriptor or one of the fields in the send_file structure. 


Interrupted function call. 


Parameter not valid. 


This error code indicates one of the following: 


e ANULL pointer was specified for the sf_struct parameter 
e The file_offset parameter specified a negative value. 
e The file_offset parameter specified a value that was greater than the file size. 


e The file_bytes parameter would have resulted in a read operation beyond the 
end of the file. 


The flags parameter specified a value that was not valid. 


Input/output error. 


There is not enough buffer space for the requested operation. 


Requested operation requires a connection. 


Function is not allowed in a job that is running with multiple threads. 


The specified descriptor does not reference a socket. 


[EOPNOTSUPP] 


[EOVERFLOW] 


[EPIPE] 


[EUNATCH] 


[EUNKNOWN] 


Operation not supported. 


The socket_descriptor parameter references a socket that does not support the 
send_file() function. The send_file() function is only valid on sockets that have an 
address family of AF_INET, #* AF_INET6,*& AF_UNIX, or AF_UNIX_CCSID and 
a socket type of SOCK_STREAM. 


Object is too large to process. 


This error code indicates one of the following: 


e The size of the file associated with file_descriptor parameter is greater than 
2 GB minus | byte. 


e The total number of bytes to be sent, header_length + file_bytes + 
trailer_length, is greater than 4 GB minus 1, the largest value that can be 
stored in the bytes_sent output field. 


Broken pipe. 


The protocol required to support the specified address family is not available at this 
time. 


Unknown system state. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. 


Usage Notes 


1. The send_file() function is only valid on sockets that have an address family of AF_INET, 2 
AF_INET6,*& AF_UNIX, or AF_UNIX_CCSID and a socket type of SOCK_STREAM. If the 
descriptor pointed to by the socket_descriptor parameter does not have the correct address family 
and socket type, -1 is returned and the errno value is set to EOPNOTSUPP. 


2. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 


oO Where multiple threads exist in the job. 


oO. The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


= Root 

m QOpenSys 
m User-defined 
gw QNTC 

gw QSYS.LIB 
gw QOPT 


3. The file_offset parameter is used to specify a base zero location in the file referenced by the 
file_descriptor parameter. If the file_bytes parameter is set to a value of 1 and the file_offset 
parameter is set to a value of 0, the first byte from the file is sent. If the file_offset parameter is set 
to a value of 1, the second byte from the file is sent. 


4. An application that uses the send_file() API may specify the O_SHARE_RDONLY or the 
O_SHARE_NONE option on the open() call when the file represented by file_descriptor is first 
opened. These options prevent other jobs or threads on the system from updating the file while it is 
being transmitted. 


5. If the O_.TEXTDATA option was specified on the open() call when the file represented by 
file_descriptor was first opened, the data is sent from the file assuming it is in textual form. The 
data is converted from the code page of the file to the code page of the application, job, or system 
as follows: 


o When reading from a true stream file, any line-formatting characters (such as carriage 
return, tab, and end-of-file) are just converted from one code page to another. 


oO When reading from record files that are being used as stream files, end-of-line characters 
are added to the end of the data in each record. 


If O_TEXTDATA was not specified on the open() call, the data is sent from the file without 
conversion. 


Regardless of whether or not O_TEXTDATA was specified on the open() call, the header_data 
and trailer_data are not translated. It is the application's responsibility to translate the header_data 
and trailer_data to the correct code page before calling send_file(). The send_file() function will 
not translate the data buffers pointed to by the header_data and trailer_data parameters prior to 
sending them. 


Note: The ability to do code-page translation is an OS/400 specific extension to the send_file() 
API. The overhead to translate the file will have an effect on the performance of the send_file() 
API. 


6. The send_file() function attempts to write header_length from the buffer pointed to by 
header_data, followed by file_bytes from the file associated with file_descriptor, followed by 
trailer_length from the buffer pointed to by trailer_data, over the connection associated with 
socket_descriptor. As the data is sent, the API will update the variables in the sf_parms structure so 
that if the send_file() API is interrupted by a signal, the application simply needs to reissue the 
send_file() call using the same parameters. 


Note: The value that is passed in for the flags parameter is ignored if the send_file() API is 
interrupted by a signal. 


7. When you develop in C-based languages and this function is compiled with LARGE _FILES 
defined, it will be mapped to send_file64(). Note that the type of the sf_struct parameter, struct 
sf_parms *, also will be mapped to type struct sf_parms64 *. 


Related Information 


@ accept_and_recv()--Wait for Connection Request and Receive the First Message That Was Sent 
e close()--Close File or Socket Descriptor 
@ open()--Open File 


@ send()--Send Data 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


send_file64()--Send a File over a Socket 
Connection 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int send_file64(int *socket_descriptor, 
struct sf_parms64 *sf_struct, 
int flags) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The send_file64() function is used to send the contents of an open file over an existing socket connection. 
The send_file64() API is a combination of the IFS read() and the sockets send() and close() APIs. Socket 
applications that transmit a file over a socket connection can, under certain circumstances, obtain improved 
performance by using send_file64(). 


send_file64() is enabled for large files. It is capable of operating on files larger than 2 GB minus 1 byte. For 
additional information on the parameters, authorities required, return values, error conditions, error 


messages, and other usage notes, see send_file()--Send a File over a Socket Connection. 


Parameters 


socket_descriptor 
(Input/Output) A pointer to the socket descriptor that is to be written to. 


sf_struct 
(Input/Output) A pointer to the send_file64 structure that contains the following: 


oO. The header buffer and length. 


o The file descriptor, the offset into the file, the file size, and the number of bytes to send 
from the file. 


oO The trailer buffer and length. 


o. The number of bytes of data that were sent. 


The structure pointed to by the sf_struct parameter is defined in <sys/socket.h>. 


struct sf_parms64 


{ 


void *header_data; 
size_t header_length; 
int file_descriptor; 
unsigned long long file_size; 

long long file_offset; 
long long file_bytes; 

void *trailer_data; 
size_t trailer_length; 


unsigned long long bytes_sent; 


flags 


(Input) A flag value that controls what is done with the socket connection after the data has been 
transmitted. 


Usage Notes 


1. When you develop in C-based languages, the prototypes for the 64-bit APIs are normally hidden. 
To use the send_file64() API, you must compile the source with the LARGE_FILE_API macro 
defined. 


2. All of the Usage Notes for send_file() apply to send_file64(). See Usage Notes in the send_file() 
API. 


API introduced: V4R4 
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setdomainname()--Set Domain Name 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int setdomainname(char *name, 
int length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The setdomainname() function is used to set the name of the domain. 


Parameters 


name 


(Input) The pointer to a character array where the domain name is stored. 


length 
(Input) The length of the name parameter. The length can be from 0 to 255 bytes. 


Return Value 


setdomainname() returns an integer. Possible values are: 


e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When setdomainname() fails, errno can be set to one of the following: 
[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
name parameter. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The length parameter specifies a negative value or a value that is greater than 
the allowed maximum length. 


e The domain name pointed to by the name parameter contains characters that 
do not belong to the invariant character set. 


[EIO] Input/output error. 
[EPERM] Operation not permitted. 


The process does not have the appropriate privileges to use setdomainname(). 


[EUNKNOWN]_ Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 
1. A process must have the * IOSYSCFG special authority to use setdomainname(). 


2. The name of the domain is set to NULL when the pointer to the domain name (pointed to by the 
name parameter) is set to NULL. 


3. setdomainname() only allows domain names that are made up of invariant characters. In addition, 
the domain name is assumed to be in the default coded character set identifier (CCSID) currently in 
effect for the job. 


Note: For exceptions to the invariant character set for some CCSIDs, see globalization topic. 


Related Information 


e getdomainname()--Retrieve Domain Name 


API introduced: V3R1 
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sethostid()--Set Host ID 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int sethostid(int host_id) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The sethostid() function is used to set a host ID. 


Parameters 


host_id 
(Input) The 32-bit host_id 


Return Value 


sethostid() returns an integer. Possible values are: 


e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When sethostid() fails, errno can be set to one of the following: 


[EIO] Input/output error. 


[EPERM] Operation not permitted. 


The process does not have the appropriate privileges to use sethostid(). 


[EUNKNOWN]_ Unknown system state. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. 


A process must have the * IOSYSCFG special authority to use the sethostid(). 


. When a process issues a sethostid(), the host_id can be accessed by ANY process that issues a 


gethostid(). 


. While many socket implementations refer to the host_id as the IP address of the machine, this is not 


necessarily the case. Many machines that support the TCP/IP protocol suite support multiple local 
IP addresses. The value contained in host_id is not used by TCP in any manner. 


. The host_id is reset to zero when an initial program load is performed. 


. The host_id is a signed integer. Therefore, a user should be careful to not confuse a return value of 


-1 from a gethostid() with an error return value. gethostid() never returns an error. 


Related Information 


gethostidQ--Retrieve Host ID Address 
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sethostname()--Set Host Name 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int sethostname(char *name, 
int length) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The sethostname() function is used to set the name of the host for a system. 


Parameters 


name 


(Input) The pointer to a character array where the host name is stored. 


length 
(Input) The length of the name parameter. 


Return Value 


sethostname() returns an integer. Possible values are: 


e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When sethostname() fails, errno can be set to one of the following: 
[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
name parameter. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The length parameter specifies a negative value or a value that is greater than 
the allowed maximum length. 


e The host name pointed to by the name parameter contains characters that are 
not invariant. 


[EPERM] Operation not permitted. 


[EIO] 


The process does not have the appropriate privileges to use sethostname(). 


Input/output error. 


[EUNKNOWN]_ Unknown system state. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. 


A process must have the * IOSYSCFG special authority to use the sethostname(). 


. Maximum length of host names is defined by [|MAXHOSTNAMELEN ] (defined in 


<sys/param.h>). 


. The host name can be set in the following two ways (and users should be aware of the implications 


of the way they choose): 


o By using option 12 (Change local domain and host names) on the Configure TCP/IP 
(CFGTCP) menu. When option 12 is used to change the local domain name or local host 
name, the system appends the local domain name to the local host name and stores the 
value for access by sethostname() and gethostname(). 


oO By using the sethostname() function. When sethostname() is used to set the host name, the 
TCP/IP configuration file is not affected. Only the field that is accessed by sethostname() 
and gethostname() is changed. 


4. The name of the host is set to NULL when the pointer to the host name (pointed to by the name 
parameter) is set to NULL. 


5. The host name is assumed to be in the default coded character set identifier (CCSID) currently in 
effect for the job. In addition, the host name must adhere to the following conventions. 


Oo 


Oo 


The first character must be either an English alphabetic character or a numeric character. 


The last character must be either an English alphabetic character, a numeric character, or a 
period (.). 


Blanks are not allowed (trailing blanks are removed). 
The special characters period(.), underscore(_), and minus(-) are allowed. 


Parts of the name separated by periods (.) cannot exceed 63 characters in length. 


Note: Each part of the name separated by periods must begin and end with an English 
alphanumeric character. 


Internet address names (in the form nnn.nnn.nnn.nnn (where nnn is a decimal number)) are 
not allowed. 


Names must be from | to 255 characters in length. 


Related Information 


gethostname()--Retrieve Host Name 
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setsockopt()--Set Socket Options 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int setsockopt (int socket_descriptor, 
int level, 
int option_name, 


char *option_value, 
int option_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int setsockopt (int socket_descriptor, 
int level, 
int option_name, 


const void *option_value, 
socklen_t option_length) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 
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The setsockopt() function is used to set socket options. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro. * 


Parameters 


socket_descriptor 


(Input) The descriptor of the socket for which options are to be set. 


level 


(Input) Whether the request applies to the socket itself or the underlying protocol being used. 


Supported values are: 
IPPROTO_IP 
IPPROTO_TCP 
SOL_SOCKET 
#°TPPROTO_IPV6 
IPPROTO_ICMPV6 


option_name 


Request applies to IP protocol layer. 
Request applies to TCP protocol layer. 
Request applies to socket layer. 
Request applies to IPv6 protocol layer. 


Request applies to ICMPv6 protocol layer. 


(Input) The name of the option to be set. The following tables list the options supported for each 
level. Assume that the option is supported for all address families unless the option is described 


otherwise. 


Note: Options directed to a specific protocol level are only supported by that protocol. An option 
that is directed to the SOL_SOCKET level always completes successfully. This provides 
compatibility with Berkeley Software Distributions implementations that also shield the 
application from protocols that do not support an option. 


Socket Options That Apply to the IP Layer (IPPROTO_IP) 
| Option | Description 


Set IP header options. This is only supported for sockets with an 
address family of AF_INET. 


IP_OPTIONS 


IP_TOS 


IP_MULTICAST_IF 


| IP_TTL 


Set Type Of Service (TOS) and Precedence in the IP header. This 
option is only supported for sockets with an address family of 
AF_INET. 


Set Time To Live (TTL) in the IP header. This option is only 
supported for sockets with an address family AF_INET. 


Set interface over which outgoing multicast datagrams should be 
sent. An option_value parameter of type in_addr is used to 
specify the local IP address that is associated with the interface 
over which outgoing multicast datagrams should be sent. An 
address of INADDR_ANY removes the previous selection. This 
option is only supported for sockets with an address family of 
AF_INET and type of SOCK_DGRAM or SOCK_RAW. 


IP_MULTICAST_TTL Set Time To Live (TTL) in the IP header for outgoing multicast 
datagrams. An option_value parameter of type char is used to set 
this value between 0 and 255. This option is only supported for 
sockets with an address family of AF_INET and type of 
SOCK_DGRAM or SOCK_RAW. 


IP_MULTICAST_LOOP Specify that a copy of an outgoing multicast datagram should be 
delivered to the sending host as long as it is a member of the 
multicast group. If this option is not set, a copy of the datagram 
will not be delivered to the sending host. An option_value 
parameter of type char is used to control loopback being on or 
off. This option is only supported for sockets with an address 
family of AF_INET and type of SOCK_DGRAM or 
SOCK_RAW. 


IP_ADD_MEMBERSHIP _| Joins a multicast group as specified in the option_value 
parameter of type struct ip_mreq. A maximum of 
IP_MAX_MEMBERSHIPS groups may be joined per socket. 
This option is only supported for sockets with an address family 
of AF_INET and type of SOCK_DGRAM or SOCK_RAW. 


IP_DROP_MEMBERSHIP | Leaves a multicast group as specified in the option_value 
parameter of type struct ip_mreq. This option is only supported 
for sockets with an address family of AF_INET and type of 
SOCK_DGRAM or SOCK_RAW. 


IP_RECVLCLIFADDR Indicates if the local interface that a datagram to be received 
should be returned. A value of 1 indicates the first 4 bytes of the 
reserved field of the sockaddr structure will contain the local 
interface. This option is only supported for sockets with an 
address family of AF_INET and type of SOCK_DGRAM. 


IP_DONTFRAG Set or reset the don't fragment flag in the IP header. This option 
is supported for sockets with an address family of AF_INET and 
type of SOCK_DGRAM or SOCK_RAW only. 


Socket Options That Apply to the TCP Layer (IPPROTO_TCP) 


| Option Description 


TCP_NODELAY 


Indicates if TCP is to buffer data. This option is only supported for sockets 
with an address family of AF_INET#* or AF_INET6*& and type of 
SOCK_STREAM. 


Socket Options That Apply to the Socket Layer (SOL_SOCKET ) 


| Option | Description 


SO_BROADCAST Enable the socket for issuing messages to a broadcast address. This 
option is only supported for sockets with an address family of 
AF_INET and type SOCK_DGRAM or SOCK_RAW. The broadcast 
address to be used may be determined by issuing an ioctl() with the 


SIOCGIFBRDADDR request. 


| Indicates if low level-debugging is active. 


Bypass normal routing mechanisms. This option is only supported by 
sockets with an address family of AF_INET#* or AF_INET6*%&. 


| SO_DEBUG 


SO_DONTROUTE 


SO_KEEPALIVE Keep the connection up by sending periodic transmissions. This 
option is only supported for sockets of an address family of AF_INET 
2» or AF_INET6% and type SOCK_STREAM. 

SO_LINGER Indicates if the system attempts delivery of any buffered data or if the 


system discards it when a close() is issued. 


For sockets that are using a connection-oriented transport service with 
an address family of AF_INET#* or AF_INET6*&, the default is off 
(which means that the system attempts to send any queued data, with 
an infinite wait-time). 


For sockets that are using a connection-oriented transport service with 
an address family of AF_TELEPHONY, the default is on with a linger 
time of 1 second (which means that the system will wait up to 1 
second to send buffered data before clearing the telephone 
connection). 


Indicates whether out-of-band data is received inline with normal 
data. This option is only supported for sockets with an address family 
of AF_INET#* or AF_INET6*. 


| SO_RCVBUF | Set the size of the receive buffer. 


SO_RCVLOWAT 


SO_OOBINLINE 


Set the size of the receive low-water mark. The default size is 1. This 
option is only supported for sockets with a type of SOCK_STREAM. 


2*SO_RCVTIMEO Set the receive timeout value. This option is not supported unless 
_XOPEN_SOURCKE is defined to be 520 or greater. * 


SO_REUSEADDR Indicates if the local socket address can be reused. This option is 
supported by sockets with an address family of AF_INET#* or 
AF_INET6%& and a type of SOCK_STREAM or SOCK_DGRAM. 


| Set the size of the send buffer. 


Set the size of the send low-water mark. This option is not supported. 


| SO_SNDBUF 
| SO_SNDLOWAT 


2SO_SNDTIMEO 


Set the send timeout value. This option is not supported unless 
_XOPEN_SOURCKE is defined to be 520 or greater. “ 


SO_USELOOPBACK | Indicates if the loopback feature is being used. This option is not 
supported. 


2» Socket Options That Apply to the IPv6 Layer (IPPROTO_IPV6) 


| Option Description 


IPV6_UNICAST_HOPS Set the hop limit value that will be used for subsequent unicast 
packets sent by this socket. An option_value parameter of type 
int is used to set this value between 0 and 255. This option is 
supported for sockets with an address family of AF_INET6 
only. 


IPV6_MULTICAST_IF Set the interface over which outgoing multicast datagrams will 
be sent. An option_value parameter of type unsigned int is used 
to set the interface index that is associated with the interface 
over which outgoing multicast datagrams will be sent. This 
option currently is not supported. 


IPV6_MULTICAST_HOPS | Set the hop limit value that will be used for subsequent multicast 
packets sent by this socket. An option_value parameter of type 
int is used to set this value between 0 and 255. If 
IPV6_MULTICAST_HOPS is not set, the default is 1. This 
option currently is not supported. 


IPV6_MULTICAST_LOOP | Set the multicast looping mode. A value of 1 (default), indicates 
that multicast datagrams sent by this system should also be 
delivered to this system as long as it is a member of the 
multicast group. If this option is 0, a copy of the datagram will 
not be delivered to the sending host. An option_value parameter 
of type unsigned int is used to set this value. This option 
currently is not supported. 


IPV6_JOIN_GROUP Joins a multicast group as specified in the option_value 
parameter of type struct ipv6_mreq. A maximum of 
IP_MAX_MEMBERSHIPS groups may be joined per socket. 
This option currently is not supported. 


IPV6_LEAVE_GROUP Leaves a multicast group as specified in the option_value 
parameter of type struct ipv6_mreq. This option currently is not 
supported. 

IPV6_V6ONLY Set the AF_INET6 communication restrictions. A non-zero 


value indicates that this AF_INET6 socket is restricted to IPv6 
communications only. This option stores an int value. This is a 
boolean option. By default this option is turned off. This option 
is supported for sockets with an address family of AF_INET6 
only. 


IPV6_CHECKSUM Set if the kernel will calculate and insert a checksum for output 
and verify the received checksum on input, discarding the 
packet if the checksum is in error for this socket. An 
option_value parameter of type int is used to set this value. If 
this option is -1 (the default), this socket option is disabled. A 
value of 0 or greater specifies an integer offset into the user data 


of where the checksum is located. This must be an even integer 
value. This option is only supported for sockets with an address 
family of AF_INET6 and type of SOCK_RAW with a protocol 
other than IPPROTO_ICMPV6. The checksum is automatically 
computed for protocol IPPROTO_ICMPV6. 


Socket Options That Apply to the ICMPv6 Layer IPPROTO_ICMPV6) 


| Option | Description 


ICMP6_FILTER | Set the ICMPv6 Type Filtering. An option_value parameter of type struct 
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option_value 


icmp6_filter, defined in <netinet/icmp6.h> is used to set this value. The 
following macros, defined in <netinet/icmp6.h> can be used to update the 
type filtering structure to specify whether or not specific ICMPv6 message 
types will be passed to the application or be blocked: 


ICMP6_FILTER_SETPASS, ICMP6_FILTER_SETBLOCK, 
ICMP6_FILTER_SETPASSALL, and ICMP6_FILTER_SETBLOCKALL. 
The default is to pass all ICMPv6 message types to the application. This 
option is only supported for sockets with an address family of AF_INET6 
and type of SOCK_RAW with a protocol of IPPROTO_ICMPV6. 


(Input) A pointer to the option value. Integer flags/values are required by setsockopt() for all the 
socket options except SO_LLINGER, IP_OPTIONS, IP_MULTICAST_IF, IP_MULTICAST_TTL, 
IP_MULTICAST_LOOP, IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP, 
#?IPV6_JOIN_GROUP, IPV6_LEAVE_GROUP, ICMP6_FILTER*&. 


Note: For the IP_TOS and IP_TTL options, only the rightmost octet (least significant octet) of the 
integer value is used. 


The following options can be set by specifying a nonzero value for the option_value parameter: 


Oo 


OO 0 00 0 0 0 


SO_BROADCAST 
SO_DEBUG 
SO_DONTROUTE 
SO_KEEPALIVE 
SO_OOBINLINE 
SO_REUSEADDR 
TCP_NODELAY 
IP_MULTICAST_LOOP 
IP_DONTFRAG 


o #IPV6_V6ONLY 
o IPV6_MULTICAST_LOOP*& 


For the SO_LINGER option, option_value is a pointer to the structure struct linger, defined in 
<sys/socket.h>. 


struct linger [ 
int l_onoff; 
int 1_linger; 


]; 


The /_onoff field determines if the linger option is set. A nonzero value indicates the linger option 
is set and is using the /_linger value. A zero value indicates that the option is not set. The /_linger 
field is the time to wait before any buffered data to be sent is discarded. The following occur on a 
close(): 


o For AF_INET# and AF_INET6*& sockets: 


m If the /_onoff value is zero, the system attempts to send any buffered data with an 
infinite wait-time. 


m If the /_onoff value is nonzero and the /_linger value is nonzero, the system 
attempts to send any buffered data for /_linger time. If l_linger time has elapsed 
and the data is still not successfully sent, it is discarded. When data is discarded, 
the remote program may receive a [ECONNRESET]. 


o For AF_INET sockets over SNA: 


m If the /_onoff value is nonzero and the /_linger value is zero, the system waits 
indefinitely (no timer is implemented). Otherwise, if the /_onoff value is nonzero 
and the /_linger value is zero, the system discards any buffered data. When data is 
discarded, the remote program may receive a [ECONNRESET]. 


o For AF_TELEPHONY sockets: 


m If the /_onoff value is zero, the system will wait until all buffered data is sent or 1 
second has elapsed, whichever occurs first, before clearing the telephone 
connection (that is, hanging up). 


m If the /_onoff value is nonzero, the system will wait until all buffered data is sent or 
L_ linger seconds have elapsed, whichever occurs first, before clearing the 
telephone connection (that is, hanging up). 


Note: An application must implement an application level confirmation. Guaranteed receipt of data 
by the partner program is required. Setting SO_LINGER does not guarantee delivery. 


2» For the SO_LRCVTIME and SO_SNDTIME options, option_value is a pointer to where the 
structure timeval is stored. The structure timeval is defined in <sys/time.h>. 


struct timeval { 
long tv_sec; 
long tv_usec; 


}; 


% 


For the IP_LOPTIONS option, option_value is a pointer to a character string representing the IP 
options as specified in RFC 791. The character string varies depending on which options are 
selected. Each option is made up of a single byte representing the option code, and may be 
followed by a length field (1 byte) and data for the option. The IP options that can be set are: 


o End of option list. Used if options do not end at end of header. 
o No operation (used to align octets in a list of options). 

o Security and handling restrictions. 
O 


Loose source routing. Used to route a datagram along a path of specified IP addresses. 
Multiple network hops are allowed between any two IP addresses on the path. 


oO Record route. Used to trace a route. 


o Stream identifier. Used to carry a SATNET stream identifier. This option has been 
deprecated by RFC 1122 and will result in an error of [EINVAL] if used. 


o Strict source routing. Used to route datagram along a path of specified IP addresses. No 
additional network hops are allowed between any two IP addresses in the path. 


oO Internet timestamp. Used to record timestamps along the route. 


For the IP_MULTICAST_IF option, option_value is a pointer to the structure in_addr, defined in 
<netinet/in.h> as: 


struct in_addr [ 
u_long s_addr; 
/* IP address * / 
]; 


The s_addr field specifies the local IP address that is associated with the interface over which 
outgoing multicast datagrams should be sent. 


For the IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP options, option_value is a 
pointer to the structure ip_mreq, defined in <netinet/in.h> as: 


struct ip_mreg [ 
struct in_addr imr_multiaddr; 
/* IP multicast address of group */ 
struct in_addr imr_interface; 
/* local IP address of interface */ 


li 


The imr_multiadadr field is used to specify the multicast group to join or leave. The imr_interface 
field is used to specify the local IP address that is associated with the interface to which this request 
applies. If INADDR_ANY is specified for the local interface, the default multicast interface will be 
selected. 


Note: Reception of IP multicast datagrams may require configuration changes to the line 
description to enable the adapter to receive packets with a multicast destination address. On 
Ethernet, for example, the Ethernet group address that is associated with the IP group address must 
be specified by the GRPADR parameter on the line description. To determine the Ethernet group 
address for a particular IP group address, the low-order 23 bits of the IP address are placed into the 
low-order 23 bits of the Ethernet group address 01.00.5E.xx.xx.xx. 


Notes: 


1. For sockets that use a connection-oriented transport service, IP options that are set using 


setsockopt() are only used if they are set prior to a connect() being issued. After the 
connection is established, any IP options that the user sets are ignored. 


2. If the IP options portion contains a source routing option, then the address in the source 
routing option overrides the destination address. The destination address may have been 
specified on an output operation (for example, on a sendto()) or on a connect(). 


3. If a socket has a type of SOCK_RAW and a protocol of IPPROTO_RAW, any IP options 
set using setsockopt() are ignored (since the user must supply the IP header data on an 
output operation as part of the data that is being transmitted). 


option_length 
(Input) The length of the option_value. 


Authorities 


No authorization is required. 


Return Value 


setsockopt() returns an integer. Possible values are: 


e -! (unsuccessful) 


e@ 0 (successful) 


Error Conditions 


When setsockopt() fails, errno can be set to one of the following: 


[EADDRINUSE] Address already in use. 
This error code indicates that the socket_descriptor parameter specified for the 
IP_ADD_MEMBERSHIP operation is already a member of the specified 
multicast group. 


[EADDRNOTAVAIL] Address not available. 
For the IP_ADD_MEMBERSHIP or IP_DROP_MEMBERSHIP operations, this 
error code indicates that an incorrect address was specified for either the 
imr_multiaddr or imr_interface parameter value. 


[EBADF] Descriptor not valid. 


[ECONNABORTED] 


[EFAULT] 


[EINVAL] 


[EIO] 


[ENOBUFS] 


[ENOPROTOOPT] 


[ENOTCONN] 


Connection ended abnormally. 


This error code indicates that the transport provider ended the connection 
abnormally because of one of the following: 


e The retransmission limit has been reached for data that was being sent 
on the socket. 


e A protocol error was detected. 


Bad address. 


The system detected an address which was not valid while attempting to access 
the option_value parameter. 


Parameter not valid. 
This error code indicates one of the following: 


e The /evel parameter specifies a level that is not supported. 


e@ The option_name parameter specifies a value that is not valid (except 
for when the level is SOL_SOCKET , in which case [ENOPROTOOPT] 
is returned). 


e The option_value parameter specifies a value that is not valid. 
e The option_length parameter specifies a negative or zero value. 


e An attempt was made to set a socket option that was read-only. 


Input/output error. 


There is not enough buffer space for the requested operation. 


The protocol does not support the specified option. 


This error code indicates one of the following: 


e@ The socket has an address family of AF_UNIX and the /evel parameter 
specified is not SOL_SOCKET . 


e The /evel parameter specifies a level of SOL_SOCKET and the 
option_name parameter specifies a value that is not valid. 


Requested operation requires a connection. 


This error code is only returned if the /evel parameter specifies a level other than 
SOL_SOCKET and the socket_descriptor parameter points to a socket that is 
using a connection-oriented transport service that has had its connection broken. 


[ENOTSOCK] The specified descriptor does not reference a socket. 


[EPERM] Operation not permitted. 


The executing user profile must have *[OS YSCFG special authority to set 
options when the level parameter specifies IPPROTO_IP and the option_value 
parameter is IP_OPTIONS. 


[ETOOMANYREFS] _ The operation would have exceeded the maximum number of references allowed 
for this socket. 


[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 
[EUNKNOWN] Unknown system state. 


Error Messages 


CPE3418E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081E Unable to set return value or error code. 


Usage Notes 


1. Socket options are defined in <sys/socket.h>, IP options are defined in <netinet/ip.h> and 
<netinet/in.h>, TCP options are defined in <netinet/tep.h>, 2*IPv6 and ICMPv6 options are 
defined in <netinet/in.h>.*& 


2. The user profile for an application that is running must have *IOSYSCFG special authority to set 
options when the /eve/ parameter specifies IPPROTO_IP and the option_value parameter is 
IP_OPTIONS. 


3. The following comments applies to the SO_SNDBUF option value: 


o For AF_INET#* and AF_INET6 “sockets over TCP of type SOCK_STREAM, the 
maximum value the SO_SNDBUF option can be set to is 8 megabytes. Anything greater 
results in an error of [ENOBUFS]. If the SO_SNDBUF option value is set to a positive 
value that is less than 512 bytes, the system automatically uses 512 bytes as the 
SO_SNDBUFEF size. 


o For AF_INET#* and AF_INET6 sockets over UDP of type SOCK_DGRAM, the 
maximum value the SO_SNDBUF option can be set to is 65535 bytes less the IP and UDP 
header sizes. Anything greater results in an error of [EINVAL]. 


4. For AF_INET sockets over SNA of type SOCK_STREAM, SO_RCVBUEF should be set before 
connection is established. After connection is established, any changes are ignored. Also, only the 
client can affect the receive buffer size. The server cannot affect it. 


5. For AF_INET sockets over SNA of type SOCK_DGRAM, both SO_SNDBUF and SO_RCVBUF 
are ignored and have no effect on processing. 


6. When a TCP connection is closed for a socket using the AF_INET 2 or AF_INET6 address 
family, the port associated with that connection is not made available until twice the Maximum 
Segment Life (MSL) time in seconds has passed. The MSL time is approximately 2 minutes. The 
SO_REUSEADDR option allows a bind() to succeed when requesting a port that is being held 
during this time frame. This can be especially useful if a server is abruptly ended and restarted. 


Notes: 


o For AF_INET#* and AF_INET6, **SOCK_ STREAM sockets, this option does not allow 
two servers to successfully issue a bind() requesting the same port number and local 
address combination. For AF_INET#* and AF_INET6, «SOCK _DGRAM sockets, the 
SO_REUSEADDR option does allow multiple servers to successfully bind to the same 
port. When broadcast or multicast datagrams are received for a given port, each server that 
is bound to that port receives a copy of the datagram provided each server has enabled the 
SO_REUSEADDR option. 


oO This option does not affect unicast datagram delivery. 


7. The following SOL_SOCKET options are not supported by AF_INET sockets over SNA. 
setsockopt() appears to succeed, but has no effect on the function of AF_INET sockets over SNA. 


o SO_BROADCAST 
o SO_DONTROUTE 
o SO_KEEPALIVE 
o SO_LINGER 


8. The option IP_DONTFRAG is not valid for multicast group destinations. 


9. Only the following SOL_SOCKET options are supported by AF_TELEPHONY sockets. For the 
others, setsockopt() appears to succeed, but has no effect on the function of the AF_TELEPHONY 
sockets. 


o SO_RCVBUF 
o SO_SNDBUF 
o SO_LINGER 


10. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the setsockopt() API is mapped to 
qso_setsockopt98().%& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e@ getsockopt()--Retrieve Information about Socket Options 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


shutdown()--End Receiving and/or Sending of 
Data on Socket 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int shutdown(int socket_descriptor, 
int how) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int shutdown(int socket_descriptor, 
int how) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


4 


The shutdown() function is used to disable reading, writing, or reading and writing on a socket. 


# There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


socket_descriptor 
(Input) The descriptor of the socket to be shut down. 


how 
(Input) The data flow path to be disabled: 


2*SHUT_RD or*& 0 No more data can be received. 
2SHUT_WR or*& | No more data can be sent. 


=SHUT_RDWR ort& 2 No more data can be sent or received. 


Authorities 


No authorization is required. 


Return Value 


shutdown() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e 0 (successful) 


Error Conditions 


When shutdown() fails, errno can be set to one of the following: 


[EBADF] Descriptor not valid. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The socket pointed to by the socket_descriptor parameter is using a 
connection-oriented transport service. Also, the transport service is in a state 
in which sends and receives are disallowed (for example, connection has been 
reset by peer). 


e The how parameter specifies a value that is not valid. 
[ENOTSOCK] _ The specified descriptor does not reference a socket. 


[EIO] Input/output error. 


[EUNATCH] The protocol required to support the specified address family is not available at this 
time. 


Note: This errno is not returned if the how parameter is 0. 


[EUNKNOWN]_ Unknown system state. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. 


Issuing a shutdown() with a how parameter of 0 causes any new data received for the socket to be 
discarded. Any input functions for this socket complete with a 0, meaning that end-of-file has been 
reached. On a BSD implementation, if the socket is being shared across multiple processes, any 
blocking input operations are deblocked by this action. However, the OS/400 sockets 
implementation of shutdown() does not cause these blocked functions to be deblocked. 


. Issuing a shutdown() with a how parameter of 1 results in all output functions being failed with an 


error of [EPIPE]. The process issuing the output operation will receive a synchronous SIGP IPE 
signal. This also sends a normal close sequence to the partner program. Receive operations issued 
by the partner program receive a return value of 0 once all previous data has been received. On a 
BSD implementation, if the socket is being shared across multiple processes or threads, any 
blocking output functions are deblocked with a return value of -1 and an error code of [EPIPE]. 
However, the OS/400 sockets implementation of shutdown() does not cause these blocked 
functions to be deblocked. 


. Issuing a shutdown() with a how parameter of 2 results in the actions listed for a how parameter of 


0 being performed first, followed by the actions listed for a how parameter of 1. 


. Issuing a shutdown() on socket connected through a SOCKS server is not supported. 


. 2’When you develop in C-based languages and an application is compiled with the 


_XOPEN_SOURCE macro defined to the value 520 or greater, the shutdown() API is mapped to 
qso_shutdown98().%& 


Related Information 


e@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e close()--Close File or Socket Descriptor 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


socket()--Create Socket 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int socket (int address_family, 


int type, 
int protocol) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The socket() function is used to create an end point for communications. The end point is represented by the 
socket descriptor returned by the socket() function. 


Parameters 


address_family 
(Input) The address family to be used with the socket. Supported values are: 


AF_INET For interprocess communications between processes on the same system or 
different systems in the Internet domain using the Internet Protocol (IPv4). 


2*AF_INET6 For interprocess communications between processes on the same system or 
different systems in the Internet domain using the Internet Protocol (IPv6 
or IPv4).%& 


AF_NS For interprocess communications between processes on the same system or 
different systems in the domain defined by the Novell or Xerox protocol 
definitions. 


2» Note: The AF_NS address family is no longer supported as of V5R2. 


AF_UNIX For interprocess communications between processes on the same system in 
the UNIX domain. 


AF_UNIX_CCSID For interprocess communications between processes on the same system in 
the UNIX domain using the Qlg_Path_Name_T structure. 


AF_TELEPHONY | For interprocess communications between processes on the same system in 
the telephony domain. 


Note: The OS/400 implementation supports communication over ISDN 
telephone networks only. 


type 
(Input) The type of communications desired. Supported values are: 


SOCK_DGRAM Indicates a datagram socket is desired. 


SOCK_SEQPACKET Indicates a full-duplex sequenced packet socket is desired. Each input 
and output operation consists of exactly one record. 


SOCK_STREAM Indicates a full-duplex stream socket is desired. 


SOCK_RAW Indicates communication is directly to the network protocols. A process 
must have the appropriate privilege *ALLOBJ to use this type of 
socket. Used by users who want to access the lower-level protocols 
directly. 


protocol 


(Input) The protocol to be used on the socket. Supported values are: 


0 Indicates that the default protocol for the type selected is to be used. 
For example, IPPROTO_TCP is chosen for the protocol if the type was 
set to SOCK_STREAM and the address family is AF_INET. 


IPPROTO_IP Equivalent to specifying the value zero (0). 

IPPROTO_TCP Indicates that the TCP protocol is to be used. 

IPPROTO_UDP Indicates that the UDP protocol is to be used. 

IPPROTO_RAW Indicates that communications is to the IP layer. 

IPPROTO_ICMP ili that the Internet Control Message Protocol (ICMP) is to be 
used. 


#IPPROTO_ICMPV6_ Indicates that the Internet Control Message Protocol (ICMPv6) is to be 
used.*& 


TELPROTO_TEL Equivalent to specifying the value zero (0). 


Note: When the type is SOCK_RAW,, the protocol can be set to some predefined protocol number from 
0-255. See Usage Notes for further details. 


Authorities 


When the SOCKET being created is of type SOCK_RAW, the thread must have *ALLOBJ special 
authority. When the thread does not have this authority, the EACCES is returned for errno. 


Return Value 


socket() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is a socket descriptor. 


Error Conditions 


When socket() fails, errno can be set to one of the following: 


[EACCES] 


[EAFNOSUPPORT] 
[EIO] 

[EMFILE] 

[ENFILE] 

[ENOBUFS] 
2[EPROTOTYPE] 
[EPROTONOSUPPORT] 
[ESOCKTNOSUPPORT] 


[EUNATCH] 


[EUNKNOWN] 


Error Messages 


Permission denied. 


Process does not have the appropriate privileges to create the socket with the 
specified type or protocol. 

The type of socket is not supported in this protocol family. 

Input/output error. 

Too many descriptions for this process. 

Too many descriptions in system. 

There is not enough buffer space for the requested operation. 

The socket type or protocols are not compatible. 

No protocol of the specified type and domain exists. 


The specified socket type is not supported. 


The protocol required to support the specified address family is not available 
at this time. 


Unknown system state. 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. The socket address families and types supported by sockets are defined in <sys/socket.h>. The 
protocols are defined in <netinet/in.h> (Internet protocols). 


2. The AF_UNIX and AF_UNIX_CCSID address family supports a protocol of 0 for both 
SOCK_STREAM and SOCK_DGRAM. 


3. 2* The AF_NS address family is no longer supported as of V5R2. & 


4. The following tables list the combinations of types and protocols that are supported for AF_INET 
and the combinations of types and protocols that are supported for AF_INET6.%& 


| Supported Combinations of Types and Protocols for AF_INET 

| Socket Type | Protocol 

| STREAM | IPPROTO_TCP (see Usage note 5) 

| DGRAM | IPPROTO_UDP 

| RAW | IPPROTO_RAW, IPPROTO_ICMP, protocol_number, (see Usage note 6) 


| “Supported Combinations of Types and Protocols for AF_INET6 

| Socket Type | Protocol 

| STREAM | IPPROTO_TCP 

| DGRAM | IPPROTO_UDP 

| RAW | IPPROTO_RAW, IPPROTO_ICMPV6, protocol_number, (see Usage note 6)*& 


5. The ALWANYNET (Allow ANYNET support) network attribute allows a customer to select 
whether a SNA transport can be used for AF_INET socket applications. 


The system administrator can see the current status of the ALWANYNET attribute and can change 
that status. (This can be done by using the Display Network Attributes (DSPNETA) and Change 
Network Attributes (CHGNETA) commands, respectively.) 


If the status is changed, the change takes effect immediately. Also, the state of the ALWANYNET 
stays the same across IPLs. For example, if the current status is *YES and the system administrator 
changes the value to *NO, the use of AF_INET over a transport other than TCP/IP is deactivated. If 
a system IPL is performed after this point, the use of AF_INET over a SNA transport remains 
deactivated after the system IPL. 


If AF_INET sockets will only be used over a TCP/IP transport, the ALWANYNET status should 
be set to *NO to improve CPU utilization. 


Note: If you are also using APPC over TCP/IP ALWANYNET status needs to be set to *YES. 


6. When the socket type is SOCK_RAW, you can specify any protocol number between 0-255. Two 
exceptions are the IPPROTO_TCP and IPPROTO_UDP protocols, which cannot be specified on a 
socket type of SOCK_RAW (if you issue socket(), you get an error with an error code of 
[EPROTONOSUPPORT]). Each raw socket is associated with one IP protocol number, and 
receives all data for that protocol. For example, if two processes create a raw socket with the same 
protocol number, and data is received for the protocol, then both processes get copies of the data. 


Protocol numbers 0 (IPPROTO_IP) and 255 (IPPROTO_RAW) have some unique characteristics. 
If a protocol number of zero is specified, then IP sends all data received from all the protocol 
numbers (except IPPROTO_TCP and IPPROTO_UDP protocols). If a protocol number of 255 is 
specified, a user must ensure that the IP header data is included in the data sent out on an output 
operation. 


Related Information 


e socketpair(--Create a Pair of Sockets 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


socketpair()--Create a Pair of Sockets 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int socketpair(int address_family, 
int type, 


int protocol, 
int *socket_vector) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <sys/socket.h> 


int socketpair(int address_family, 
int type, 


int protocol, 
int socket_vector[2]) 


Service Program Name: QSOSRV1 
Default Public Authority: *USE 


Threadsafe: Yes 


% 


The socketpair() function is used to create a pair of unnamed, connected sockets in the AF_UNIX or 
AF_UNIX_CCSID address_family. 


2 There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


address_family 
(Input) The address family to be used with the sockets. Supported values are: 


AF_UNIX or AF_UNIX_CCSID For interprocess communications between processes on the 
same system in the UNIX domain. 


type 
(Input) The type of communications desired. Supported values are: 
SOCK_DGRAM es$Indicates a datagram socket is desired. 
SOCK_STREAM Indicates a full-duplex stream socket is desired. 
protocol 
(Input) The protocol to be used on the sockets. Supported values are: 
0 Indicates the default protocol for the type selected is to be used. 
Authorities 


No authorization is required. 


Return Value 


socketpair() returns an integer. Possible values are: 
e -! (unsuccessful) 


e 0 (successful) 


Error Conditions 


When socketpair() fails, errno can be set to one of the following: 


[EAFNOSUPPORT] The type of socket is not supported in this protocol family. 


[EFAULT] Bad address. 


[EINVAL] Parameter not valid. 


[EIO] Input/output error. 


[EMFILE] Too many descriptions for this process. 

[ENFILE] Too many descriptions in system. 

[ENOBUFS] There is not enough buffer space for the requested operation. 
[EOPNOTSUPP] Operation not supported. 


[EPROTONOSUPPORT] No protocol of the specified type and domain exists. 
[ESOCKTNOSUPPORT] | The specified socket type is not supported. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. The socket address families and types supported by sockets are defined in <sys/socket.h>. 


2. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the socketpair() API is mapped to 
qso_socketpair98().%& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e@ socket()--Create Socket 


API Introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


takedescriptor()--Receive Socket Access from 
Another Job 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


int takedescriptor(char *source_job) 


Service Program Name: QSOSRV1 


Default Public Authority: *USE 


Threadsafe: Yes 


The takedescriptor() function is used to obtain a descriptor in one OS/400 job which was passed from 
another OS/400 job by a givedescriptor(). 


Parameters 
source_job 


(Input) A pointer to the internal job identifier that identifies the source job from which to receive a 
passed descriptor. 


Return Value 


takedescriptor() returns an integer. Possible values are: 


e -! (unsuccessful) 


e n (successful), where n is a descriptor. 


Error Conditions 
When takedescriptor() fails, errno can be set to one of the following: 


[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
source_job parameter. 


[EINVAL] Parameter not valid. 


The source_job parameter points to data that is not valid. 


[EMFILE] Too many descriptions for this process. 


[EIO] 


Input/output error. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. 


This function can only obtain a descriptor if the sender of the descriptor referenced the job that this 
takedescriptor() is issued in by explicitly specifying this job's identification on the target_job 
parameter of the givedescriptor(). 


. If the source_job parameter is a NULL pointer, then a descriptor can be received from any job 


which issues a givedescriptor() that references the job in which takedescriptor() is issued. 


. If no descriptor is available to be received, the takedescriptor() is blocked. 


. If both the job in which the givedescriptor() is issued and the job specified by the target_job 


parameter end while a descriptor is in transit, the descriptor is reclaimed by the system, and the 
resource that it represents is closed. 


. The information to specify in the target_job parameter of the givedescriptor() and in the source_job 


parameter of the takedescriptor() can be obtained in the actual target job by using a work 
management API (for example, QUSRJOBD to retrieve the internal job identifier. 


. For files and directories, takedescriptor() is only supported for objects in the root and QOpenSys 


file systems. 


Related Information 


@ givedescriptor()--Pass Descriptor Access to Another Job 


e sendmsg()--Send Data or Descriptors or Both 


@ recvmsg()--Receive Data or Descriptors or Both 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


write()--Write to Descriptor 


Syntax 


#include <unistd.h> 


ssize_t write 
(int file_descriptor, const void *buf, size_t nbyte); 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The write() function writes nbyte bytes from buf to the file or socket associated with file_descriptor. nbyte 
should not be greater than INT_MAX (defined in the <limits.h> header file). If nbyte is zero, write() simply 
returns a value of zero without attempting any other action. 


If file_descriptor refers to a "regular file" (a stream file that can support positioning the file offset) or any other 
type of file on which the job can do an Iseek() operation, write() begins writing at the file offset associated with 
file_descriptor, unless O_APPEND is set for the file (see below). A successful write() increments the file offset 
by the number of bytes written. If the incremented file offset is greater than the previous length of the file, the 
length of the file is set to the new file offset. 


If O_APPEND (defined in the <fentl.h> header file) is set for the file, write() sets the file offset to the end of 
the file before writing the output. 


If there is not enough room to write the requested number of bytes (for example, because there is not enough 
room on the disk), the writeQ) function writes as many bytes as the remaining space can hold. 


If write() is successful and nbyte is greater than zero, the change and modification times for the file are updated. 


If file_descriptor refers to a descriptor obtained using the open() function with O_TEXTDATA specified, the 
data is written to the file assuming it is in textual form. The maximum number of bytes on a single write that 
can be supported for text data is 2,147,483,408 (2GB - 240) bytes. The data is converted from the code page of 
the application, job, or system to the code page of the file as follows: 


e When writing to a true stream file, any line-formatting characters (such as carriage return, tab, and 
end-of-file) are just converted from one code page to another. 


e When writing to a record file that is being used as a stream file: 


o End-of-line characters are removed. 


oO Records are padded with blanks (for a source physical file member) or nulls (for a data physical 
file member). 


oO Tab characters are replaced by the appropriate number of blanks to the next tab position. 


There are some important considerations if O_CCSID was specified on the open(). 


e The write() will attempt to convert all of the data in the user's buffer. Successfully converted data will 
be written. Unconverted data is usually assumed to be a partial character. Partial characters will be 
buffered internally and data from the next consecutive write will be appended to the buffered data. If 
incorrect data is provided on a consecutive write, the write may fail with the [ECONVERT] error. 


If an Iseek() is performed, the file is closed, or the current job is ended, the buffered data will be 
discarded. Discarded data will not be written to the file. See lseek()--Set File Read/Write Offset for 


more information. 


e Because of the above consideration and because of the possible expansion or contraction of converted 
data, applications using the O_CCSID flag should avoid assumptions about data size and the current file 
offset. For example, the user may supply a buffer to 100 bytes, but after an application has written the 
buffer to a new file, the file size may be 50, 200, or something else, depending on the CCSIDs involved. 


If O_TEXTDATA was not specified on the open(), the data is written to the file without conversion. The 
application is responsible for handling the data. 


When file_descriptor refers to a socket, the write() function writes to the socket identified by the socket 
descriptor. 


Note: When the write completes successfully, the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits of 
the file mode will be cleared. If the write is unsuccessful, the bits are undefined.> 


Write requests to a pipe or FIFO are handled the same as a regular file, with the following exceptions: 
e The S_ISUID and S_ISGID file mode bits will not be cleared. 


e There is no file offset associated with a pipe or FIFO. Each write request will append to the end of the 
pipe or FIFO. 


e Write requests of [PIPE_BUF] bytes or less will not be interleaved with data from other threads 
performing writes on the same pipe or FIFO. Writes of greater than [PIPE BUF] bytes may have data 
interleaved on arbitrary boundaries with writes by other threads, whether or not the O NONBLOCK 
flag of the file status flags is set. 


e If the O NONBLOCK flag was not specified and the pipe or FIFO is full, the write request will block 
the calling thread until the requested amount of data in nbyte is written. 


e If the O NONBLOCK flag was specified, then the following pertain to various write requests: 
oO The write() function will not block the calling thread. 


o A write request for [PIPE_BUF] or fewer bytes will have the following effect: 


If there is sufficient space available in the pipe or FIFO, write() will transfer all the data and 
return the number of bytes requested. If there is not sufficient space in the pipe or FIFO, write() 
will transfer no data, return -1, and set errno to [EAGAIN]. 


o A write request for more than [PIPE BUF] bytes will cause one of the following: 


mg When at least one byte can be written, write() will transfer what it can and return the 
number of bytes written. 


m= When no data can be written, write() will transfer no data, return -1, and set errno to 
[EAGAIN]. 


Parameters 


file_descriptor 


(Input) The descriptor of the file to which the data is to be written. 


buf 


(Input) A pointer to a buffer containing the data to be written. 


nbyte 
(Input) The size in bytes of the data to be written. 


Authorities 


No authorization is required. 


Return Value 


value write() was successful. The value returned is the number of bytes actually written. This number is 
less than or equal to nbyte. 


- write() was not successful. The errno global variable is set to indicate the error. 


Error Conditions 


If write() is not successful, errno usually indicates one of the following errors. Under some conditions, errno 
could indicate an error other than those listed here. 


[EACCES] Permission denied. 


An attempt was made to access an object in a way forbidden by its object access 
permissions. 


The thread does not have access to the specified file, directory, component, or 
path. 


If you are accessing a remote file through the Network File System, update 
operations to file permissions at the server are not reflected at the client until 
updates to data that is stored locally by the Network File System take place. 
(Several options on the Add Mounted File System (ADDMFS) command 
determine the time between refresh operations of local data.) Access to a remote 
file may also fail due to different mappings of user IDs (UID) or group IDs (GID) 
on the local and remote systems. 


If writing to a socket, this error code indicates one of the following: 


e The destination address specified is a broadcast address and the socket 
option SO_LBROADCAST was not set (with a setsockopt()). 


[EAGAIN] 


[EBADF] 


[EBADFID] 


[EBUSY] 


[EDAMAGE] 


[EFAULT] 


[EFBIG] 


2[EINTR] 


e The process does not have the appropriate privileges to the destination 
address. This error code can only be returned on a socket with an address 
family of AF_INET and a type of SOCK_DGRAM. 


Operation would have caused the process to be suspended. 


If file_descriptor refers to a pipe or FIFO that has its O_NONBLOCK flag set, this 
error occurs if the write() would have blocked the calling thread. 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not open, or 
a read or write request was made to a file that is not open for that operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or this write() 
request was made to a file that was only open for reading. 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as soon 
as possible. 


Resource busy. 

An attempt was made to use a system resource that is not available at this time. 
A damaged object was encountered. 

A referenced object is damaged. The object cannot be used. 

The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that is 
not valid. 


While attempting to access a parameter passed to this function, the system 
detected an address that is not valid. 


Object is too large. 


The size of the object would exceed the system allowed maximum size #* or the 
process soft file size limit. 


The file is a regular file, nbyte is greater than 0, and the starting offset is greater 
than or equal to 2 GB minus 2 bytes. 


Interrupted function call.“ 


[EINVAL] 


[EIO] 


2[EJRNDAMAGE] 


[EJRNENTTOOLONG] 


[EJRNINACTIVE] 


[EJRNRCVSPC] 


[ENEWJRN] 


[ENEWJRNRCV] 


[ENOMEM] 


The value specified for the argument is not correct. 


A function was passed incorrect argument values, or an operation was attempted 
on an object and the operation specified is not supported for that type of object. 


An argument value is not valid, out of range, or NULL. 


The file system that the file resides in does not support large files, and the starting 
offset exceeds 2GB minus 2 bytes. 


Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 
Journal damaged. 


A journal or all of the journal's attached journal receivers are damaged, or the 
journal sequence number has exceeded the maximum value allowed. This error 
occurs during operations that were attempting to send an entry to the journal. 


Entry too large to send. 
The journal entry generated by this operation is too large to send to the journal. 
Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during 
operations that were attempting to send an entry to the journal. 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the storage 
limit has been exceeded for the system, the object, the user profile, or the group 
profile. This error occurs during operations that were attempting to send an entry 
to the journal. 


New journal is needed. 


The journal was not completely created, or an attempt to delete it did not complete 
successfully. This error occurs during operations that were attempting to start or 
end journaling, or were attempting to send an entry to the journal. 


New journal receiver is needed. 


A new journal receiver must be attached to the journal before entries can be 
journaled. This error occurs during operations that were attempting to send an 
entry to the journal. *& 


Storage allocation request failed. 
A function needed to allocate storage, but no storage is available. 


There is not enough memory to perform the requested function. 


[ENOSPC] 


[ENOTAVAIL] 


[ENOTSAFE] 


2 [ENXIO] 


[ERESTART] 


[ETRUNC] 


[ESTALE] 


[EUNKNOWN] 


No space available. 

The requested operations required additional space on the device and there is no 
space left. This could also be caused by exceeding the user profile storage limit 
when creating or transferring ownership of an object. 

Insufficient space remains to hold the intended file, directory, or link. 


Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim Storage 
(RCLSTG) processing. 


To recover from this error, wait until processing has completed for the 
independent ASP. 


Function is not allowed in a job that is running with multiple threads. 
No such device or address. 

A system call was interrupted and may be restarted. 

Data was truncated on an input, output, or update operation. 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


Unknown system state. 


The operation failed because of an unknown system state. See any messages in the 
job log and correct any errors that are indicated, thenretry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNREFUSED] _ The destination socket refused an attempted connect operation. 


[EDESTADDRREO] 


[EHOSTDOWN] 


This error code can only be returned on sockets that use a connectionless transport 
service. 


Operation requires destination address. 


A destination address has not been associated with the socket pointed to by the fildes 
parameter. This error code can only be returned on sockets that use a connectionless 
transport service. 


A remote host is not available. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


[EHOSTUNREACH] 


[EINTR] 


[EMSGSIZE] 


[ENETDOWN] 


[ENETUNREACH] 


[ENOBUFS] 


[ENOTCONN] 


[EPIPE] 


[EUNATCH] 


[EWOULDBLOCK] 


A route to the remote host is not available. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


Interrupted function call. 


Message size out of range. 


The data to be sent could not be sent atomically because the size specified by nbyte is 
too large. 


The network is not currently available. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


Cannot reach the destination network. 


This error code can only be returned on sockets that use a connectionless transport 
service. 


There is not enough buffer space for the requested operation. 


Requested operation requires a connection. 


This error code can only be returned on sockets that use a connection-oriented 
transport service. 


Broken pipe. 


The protocol required to support the specified address family is not available at this 
time. 


Operation would have caused the thread to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following errors: 


[EADDRNOTAVAIL] 


[ECONNABORTED] 


[ECONNREF USED] 


[ECONNRESET] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


Address not available. 


Connection ended abnormally. 


The destination socket refused an attempted connect operation. 


A connection with a remote socket was reset by that socket. 


A remote host is not available. 


A route to the remote host is not available. 


[ENETDOWN] The network is not currently available. 

[ENETRESET] A socket is connected to a host that is no longer available. 
[ENETUNREACH] Cannot reach the destination network. 

[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 
[EUNATCH] The protocol required to support the specified address family is not available at this 
time.> 


Error Messages 


The following messages may be sent from this function: 
Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
CPFA081 E Unable to set return value or error code. 


CPFAOD4 E File system error occurred. Error number &1. 


Usage Notes 
1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 
m QOpenSys 


m User-defined 


mw QNTC 

= QSYS.LIB 

m = Independent ASP QSYS.LIB & 
= QOPT 


2. QSYS.LIB # and independent ASP QSYS.LIB * File System Differences 


This function will fail with error code [ENOTSAFE] if the object on which this function is operating is 
a save file and multiple threads exist in the job. 


If the file specified is a save file, only complete records will be written into the save file. A write() 
request that does not provide enough data to completely fill a save file record will cause the partial 
record's data to be saved by the file system. The saved partial record will then be combined with 
additional data on subsequent write()'s until a complete record may be written into the save file. If the 
save file is closed prior to a saved partial record being written into the save file, then the saved partial 
record is discarded, and the data in that partial record will need to be written again by the application. 


A successful write() updates the change, modification, and access times for a database member using 
the normal rules that apply to database files. At most, the access time is updated once per day. 


You should be careful when writing end-of-file characters in the QSYS.LIB # and independent ASP 
QSYS.LIB file systems. These file systems *& end-of-file characters are symbolic; that is, they are 
stored outside the file member. However, some situations can result in actual, nonsymbolic end-of-file 
characters being written to a member. These nonsymbolic end-of-file characters could cause some tools 
or utilities to fail. For example: 


o. If you previously wrote an end-of-file character as the last character of a member, do not 
continue to write data after that end-of-file character. Continuing to write data will cause a 
nonsymbolic end-of-file to be written. As a result, a compile of the member could fail. 


o. If you previously wrote an end-of-file character as the last character of a member, do not write 
other end-of-file characters preceding it in the file. This will cause a nonsymbolic end-of-file to 
be written. As a result, a compile of the member could fail. 


o. If you previously used the integrated file system interface to manipulate a member that contains 
an end-of-file character, avoid using other interfaces (such as the Source Entry Utility or 
database reads and writes) to manipulate the member. If you use other interfaces after using the 
integrated file system interface, the end-of-file information will be lost. 


3. QOPT File System Differences 
The change and modification times of the file are updated when the file is closed. 


When writing to files on volumes formatted in Universal Disk Format (UDF), byte locks on the range 
being written are ignored. 


4. Network File System Differences 


Local access to remote files through the Network File System may produce unexpected results due to 
conditions at the server. Once a file is open, subsequent requests to perform operations on the file can 
fail because file attributes are checked at the server on each request. If permissions on the file are made 
more restrictive at the server or the file is unlinked or made unavailable by the server for another client, 
your operation on an open file descriptor will fail when the local Network File System receives these 
updates. The local Network File System also impacts operations that retrieve file attributes. Recent 
changes at the server may not be available at your client yet, and old values may be returned from 


operations (several options on the Add Mounted File System (ADDMEFS) command determine the time 
between refresh operations of local data). 


Reading and writing to files with the Network File System relies on byte-range locking to guarantee 
data integrity. To prevent data inconsistency, use the fentl() API to get and release these locks. 

5. QFileSvr.400 File System Differences 
The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will be 
received. 


6. Sockets Usage Notes 


1. writeQ only works with sockets on which a connect() has been issued, since it does not allow 
the caller to specify a destination address. 


2. To broadcast on an AF_INET socket, the socket option SO.LBROADCAST must be set (with a 
setsockopt()). 


3. When using a connection-oriented transport service, all errors except [EUNATCH] and 
[EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following 
occurs: 


= A connection that is in progress is unsuccessful. 

m= Anestablished connection is broken. 
To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input 
operation (for example, read()). 


7. For the file systems that do not support large files, write() will return [EINVAL] if the starting offset 
exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that do support 
large files, writeQ) will return [EFBIG] if the starting offset exceeds 2GB minus 2 bytes and the file was 
not opened for large file access. 


8. Using this function successfully on the 4 /dev/null or /dev/zero *& character special file results in a 
return value of the total number of bytes requested to be written. No data is written to the character 
special file. In addition, the change and modification times for the file are updated. 


9. 2 If the write exceeds the process soft file size limit, signal SIFXFSZ is issued. 


Related Information 


e The <fentl.h> file (see Header Files for UNIX-Type Functions) 


e The <unistd.h> file (see Header Files for UNIX-Type Functions) 


@ creat()--Create or Rewrite File 


e dupQ--Duplicate Open File Descriptor 


e@ dup2Q--Duplicate Open File Descriptor to Another Descriptor 


e fentlQ--Perform File Control Command 

e ioctl()--Perform I/O Control Request 

e@ lseek()--Set File Read/Write Offset 

@ open()--Open File 

e * pread()--Read from Descriptor with Offset 

@ pread64()--Read from Descriptor with Offset (large file enabled) 
@ pwriteQ--Write to Descriptor with Offset 

@ pwrite64()--Write to Descriptor with Offset (large file enabled) 
e read()--Read from Descriptor 

e@ readv()--Read from Descriptor Using Multiple Buffers 

e send()--Send Data 

e sendmsg()--Send Data or Descriptors or Both 

e sendto()--Send Data 


@ writevQ--Write to Descriptor Using Multiple Buffers 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example writes a specific number of bytes to a file: 


#include <unistd.h> 
#include <sys/types.h> 
#include <sys/stat.h> 
#include <fcntl.h> 
#include <stdio.h> 


#define mega_string_len 1000000 


main() { 
char *mega_string; 
int file_descriptor; 
int ret; 
char fn[]="write.file"; 


if ((mega_string = (char*) malloc(mega_string_len)) == NULL) 
perror("malloc() error"); 

else if ((file_descriptor = creat (fn, S_IWUSR)) < 0) 

perror("creat() error"); 


else { 
memset (mega_string, 'O', 
if ((ret = write(file_descriptor, 
perror("write() error"); 
else printf("write() wrote %d bytes\n", 
if (close(file_descriptor) != 0) 
perror("close() error"); 
if (unlink(fn)!= 0) 
perror("unlink() error"); 


mega_string_len) ; 
mega_string, mega_string_len)) == 


ret); 


} 
Output: 


write() wrote 1000000 bytes 
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writev()--Write to Descriptor Using Multiple 
Buffers 


Syntax 


#include <sys/types.h> 
#include <sys/uio.h> 


int writev(int descriptor, 


struct iovec *io_vector[], 
int vector_length) 


Service Program Name: QPOLLIB 1 


Default Public Authority: *USE 


Threadsafe: Conditional; see Usage Notes. 


The writev() function is used to write data to a file or socket descriptor. writev() provides a way for the data 
that is going to be written to be stored in several different buffers (scatter/gather I/O). 


Note: When the write completes successfully, the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits 
of the file mode will be cleared. If the write is unsuccessful, the bits are undefined. 


See write()--Write to Descriptor for more information related to writing to a descriptor. 


Parameters 


descriptor 


(Input) The descriptor to which the data is to be written. The descriptor refers to either a file or a 
socket. 


io_vector[| 


(Input) The pointer to an array of type struct iovec. struct iovec contains a sequence of pointers to 
buffers in which the data to be written is stored. The structure pointed to by the io_vector parameter 
is defined in <sys/uio.h>. 


struct iovec { 
void *iov_base; 
size_t iov_len; 


} 
iov_base and iov_len are the only fields in iovec used by sockets. iov_base contains the pointer to a 
buffer and iov_len contains the buffer length. The rest of the fields are reserved. 
vector_length 


(Input) The number of entries in io_vector. 


Authorities 


No authorization is required. 


Return Value 


writev() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is the number of bytes written. 


Error Conditions 


If writev() is not successful, errno usually indicates one of the following errors. Under some conditions, 
errno could indicate an error other than those listed here. 


[EACCES] 


[EAGAIN] 


Permission denied. 


An attempt was made to access an object in a way forbidden by its object 
access permissions. 


The thread does not have access to the specified file, directory, component, or 
path. 


If you are accessing a remote file through the Network File System, update 
operations to file permissions at the server are not reflected at the client until 
updates to data that is stored locally by the Network File System take place. 
(Several options on the Add Mounted File System (ADDMEFS) command 
determine the time between refresh operations of local data.) Access to a 
remote file may also fail due to different mappings of user IDs (UID) or group 
IDs (GID) on the local and remote systems. 


If writing to a socket, this error code indicates one of the following: 


e The destination address specified is a broadcast address and the socket 
option SO_.BROADCAST was not set (with a setsockopt()). 


e@ The process does not have the appropriate privileges to the destination 
address. This error code can only be returned on a socket with an 
address family of AF_INET and a type of SOCK_DGRAM. 


Operation would have caused the process to be suspended. 


[EBADF] 


[EBADFID] 


[EBUSY] 


[EDAMAGE] 


[EFAULT] 


[EFBIG] 


2[EINTR] 


[EINVAL] 


Descriptor not valid. 


A file descriptor argument was out of range, referred to a file that was not 
open, or a read or write request was made to a file that is not open for that 
operation. 


A given file descriptor or directory pointer is not valid for this operation. The 
specified descriptor is incorrect, or does not refer to an open file. Or this 
writev() request was made to a file that was only open for reading. 


A file ID could not be assigned when linking an object to a directory. 
The file ID table is missing or damaged. 


To recover from this error, run the Reclaim Storage (RCLSTG) command as 
soon as possible. 


Resource busy. 


An attempt was made to use a system resource that is not available at this 
time. 


A damaged object was encountered. 
A referenced object is damaged. The object cannot be used. 
The address used for an argument is not correct. 


In attempting to use an argument in a call, the system detected an address that 
is not valid. 


While attempting to access a parameter passed to this function, the system 
detected an address that is not valid. 


Object is too large. 


The size of the object would exceed the system allowed maximum size #*or 
the process soft file size limit. 


The file is a regular file, nbyte is greater than 0, and the starting offset is 
greater than or equal to 2GB minus 2 bytes. 


Interrupted function call.“ 


The value specified for the argument is not correct. 

A function was passed incorrect argument values, or an operation was 
attempted on an object and the operation specified is not supported for that 
type of object. 


An argument value is not valid, out of range, or NULL. 


The file resides in a file system that does not support large files, and the 
starting offset exceeds 2GB minus 2 bytes. 


[EIO] 


2*[EJRNDAMAGE] 


[EJRNENTTOOLONG] 


[EJRNINACTIVE] 


[EJRNRCVSPC] 


[ENEWJRN] 


[ENEWJRNRCV] 


[ENOMEM] 


[ENOSPC] 


Input/output error. 

A physical I/O error occurred. 

A referenced object may be damaged. 
Journal damaged. 


A journal or all of the journal's attached journal receivers are damaged, or the 
journal sequence number has exceeded the maximum value allowed. This 
error occurs during operations that were attempting to send an entry to the 
journal. 


Entry too large to send. 


The journal entry generated by this operation is too large to send to the 
journal. 


Journal inactive. 


The journaling state for the journal is *INACTIVE. This error occurs during 
operations that were attempting to send an entry to the journal. 


Journal space or system storage error. 


The attached journal receiver does not have space for the entry because the 
storage limit has been exceeded for the system, the object, the user profile, or 
the group profile. This error occurs during operations that were attempting to 
send an entry to the journal. 


New journal is needed. 


The journal was not completely created, or an attempt to delete it did not 
complete successfully. This error occurs during operations that were 
attempting to start or end journaling, or were attempting to send an entry to 
the journal. 


New journal receiver is needed. 
A new journal receiver must be attached to the journal before entries can be 


journaled. This error occurs during operations that were attempting to send an 
entry to the journal.“ 


Storage allocation request failed. 

A function needed to allocate storage, but no storage is available. 

There is not enough memory to perform the requested function. 

No space available. 

The requested operations required additional space on the device and there is 
no space left. This could also be caused by exceeding the user profile storage 


limit when creating or transferring ownership of an object. 


Insufficient space remains to hold the intended file, directory, or link. 


[ENOTAVAIL] 


[ENOTSAFE] 


#[ERESTART] 


[ESTALE] 


[ETRUNC] 


[EUNKNOWN] 


Independent Auxiliary Storage Pool (ASP) is not available. 


The independent ASP is in Vary Configuration (VRYCFG), or Reclaim 
Storage (RCLSTG) processing. 


To recover from this error, wait until processing has completed for the 
independent ASP. 


Function is not allowed in a job that is running with multiple threads. 


A system call was interrupted and may be restarted.*& 


File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file 
may have been deleted at the server. 


Data was truncated on an input, output, or update operation. 


Unknown system state. 


The operation failed because of an unknown system state. See any messages 
in the job log and correct any errors that are indicated, then retry the operation. 


When the descriptor refers to a socket, errno could indicate one of the following errors: 


[ECONNREFUSED] 


[EDESTADDRREQ] 


[EHOSTDOWN] 


[EHOSTUNREACH] 


[EINTR] 


[EMSGSIZE] 


The destination socket refused an attempted connect operation. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Operation requires destination address. 


A destination address has not been associated with the socket pointed to by the 
fildes parameter. This error code can only be returned on sockets that use a 
connectionless transport service. 


A remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


A route to the remote host is not available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


Interrupted function call. 


Message size out of range. 


The data to be sent could not be sent atomically because the size specified by 
nbyte is too large. 


[ENETDOWN] The network is not currently available. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


[ENETUNREACH] Cannot reach the destination network. 


This error code can only be returned on sockets that use a connectionless 
transport service. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTCONN] Requested operation requires a connection. 


This error code can only be returned on sockets that use a connection-oriented 
transport service. 


[EPIPE] Broken pipe. 
[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 


[EWOULDBLOCK] _ Operation would have caused the thread to be suspended. 


If interaction with a file server is required to access the object, errno could indicate one of the following 
errors: 

[EADDRNOTAVAIL] Address not available. 

[ECONNABORTED] Connection ended abnormally. 

[ECONNREFUSED] _ The destination socket refused an attempted connect operation. 

[ECONNRESET] A connection with a remote socket was reset by that socket. 

[EHOSTDOWN] A remote host is not available. 

[EHOSTUNREACH] _ A route to the remote host is not available. 

[ENETDOWN] The network is not currently available. 


[ENETRESET] A socket is connected to a host that is no longer available. 


[ENETUNREACH] Cannot reach the destination network. 


[ESTALE] File or object handle rejected by server. 


If you are accessing a remote file through the Network File System, the file may 
have been deleted at the server. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 
[EUNATCH] The protocol required to support the specified address family is not available at 
this time. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF3CF2 E Error(s) occurred during running of &1 API. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
CPFA081 E Unable to set return value or error code. 


CPFA0D4 E File system error occurred. Error number &1. 


Usage Notes 


1. This function will fail with error code [ENOTSAFE] when all the following conditions are true: 
oO Where multiple threads exist in the job. 


oO The object on which this function is operating resides in a file system that is not threadsafe. 
Only the following file systems are threadsafe for this function: 


m Root 

m QOpenSys 

m User-defined 

gw QNTC 

mw QSYS.LIB 

m *Independent ASP QSYS.LIB 
mw QOPT 


2. writev() only works with sockets on which a connect() has been issued, since the call does not 
allow the caller to specify a destination address. 


3. writev() is an atomic operation on sockets of type SOCK_DGRAM and SOCK_RAW in that it 


10. 


produces one packet of data every time it is issued. For example, a writev() to a datagram socket 
results in a single datagram. 


. To broadcast on an AF_INET socket, the socket option SO_.BROADCAST must be set (with a 


setsockopt()). 


. When using a connection-oriented transport service, all errors except [EUNATCH] and 


[EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following 
occurs: 


o Aconnection that is in progress is unsuccessful. 
o Anestablished connection is broken. 


To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation 
(for example, read()). 


. For the file systems that do not support large files, writev() will return [EINVAL] if the starting 


offset exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that 
do support large files, writev() will return [EFBIG] if the starting offset exceeds 2GB minus 2 
bytes and the file was not opened for large file access. 


. QFileSvr.400 File System Differences 


The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will 
be received. 


. QOPT File System Differences 


When writing to files on volumes formatted in Universal Disk Format (UDF), byte locks on the 
range being written are ignored. 


. Using this function successfully on the dev/null #¥or /dev/zero “character special file results in a 


return value of the total number of bytes requested to be written. No data is written to the character 
special file. In addition, the change and modification times for the file are updated. 


“If the write exceeds the process soft file size limit, signal SIFXFSZ is issued. 


Related Information 


The <fentl.h> file (see Header Files for UNIX-Type Functions) 


The <unistd.h> file (see Header Files for UNIX-Type Functions) 
creat()--Create or Rewrite File 


dupQ--Duplicate Open File Descriptor 


dup2()--Duplicate Open File Descriptor to Another Descriptor 


fcentlQ--Perform File Control Command 


e ioctlO--Perform I/O Control Request 


e lseek()--Set File Read/Write Offset 


@ open()--Open File 


e@ read()--Read from Descriptor 


e@ readv()--Read from Descriptor Using Multiple Buffers 


e send()--Send Data 


e sendmsg()--Send Data or Descriptors or Both 


e@ sendtoQ--Send Data 


@ writeQ--Write to Descriptor 


API introduced: V3R1 
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> 


Using XOPEN_SOURCE for UNIX 98 Compatibility 


There are two versions of most sockets APIs. The base OS/400 API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with 
BSD 4.4 and the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface by defining the XXOPEN_SOURCE macro 
to a value of 520 or greater. 


When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, some sockets 
APIs are mapped to internal names, as shown in the following table: 


| Mappedname | — Internalname = 
| endhostent() | qso_endhostent98).— 
| gethostname() | ~—_qso_gethostname98()— 
| gethostname_r() | qso_gethostname_r98Q) 
| getsockname() | qso_getsockname98()__— 
[ —sendto) §~— [| qso_sendto98() 


| setprotoent() | —_qso_setprotoent98() 
| setservent() | —_qso_setprotoent98()_ 
[ —socket() [| qso_socket98) 


Application not using C-based languages can use the internal names if necessary. 


Using _XOPEN_SOURCE also changes some of the structures used by sockets to match BSD 4.4/UNIX 98 standards. The differences are summarized in the 
following table: 


BSD 4.3 structure BSD 4.4/UNIX 98 compatible structure 


typedef int socklen_t; 
typedef uchar sa_family_t; 


typedef int socklen_t; 
typedef unsigned short sa_family_t; 


struct sockaddr { struct sockaddr { 


u_short sa_family; uint8_t sa_len; 

— = Yi sa_family_t sa_family; 

Shee Sp taea als char sa_data[14]; 
ame, v 


di 


struct sockaddr_un { struct sockaddr_un { 


, uint8_t sun_len; 
short sun_family; : ‘ 
Shae sun_path[126]; sa_family_t sun_family; 
—P ’ char sun_path[126]; 


‘i 


struct sockaddr_in { Src Bee coke e nat 


short sin_family; uints_t sin_len; 

io5 4 sa_family_t sin_family; 
Ges r te sin_port; pu -shert sin_port; 
SELNGE se issdaer pit Radel y struct in_addr sin ada 
char sin_zero[8]; anes = Bic eere el : 


struct sockaddr_in6 { ser uch pockaddr ing 


; : F uint8_t sin6_len; 
ea_family-= pane familys sa family € ei Heron Wye 
in_port_t sin6_port; iA BOeE eS sine pore, id 
uint32_t sin6_flowinfo; es = : ’ . 

; ; uint32_t sin6_flowinfo; 
struct in6_addr sin6_addr; ; : : 
uint32.t gine scoexia: struct in6é_addr sin6_addr; 

SPeOP eset uint32_t sin6_scope_id; 


struct msghdr { struct msghdr { 


void *msg_name; 
caddr_t msg_name; 
; socklen_t msg_namelen; 
int msg_namelen; : % : 

; 5 ; struct iovec *msg_iov; 
struct lovec *msg_1ov; 3 i 
: ; int msg_iovlen; 
int msg_iovlen; z 
; void *msg_control; 

caddr_t msg_accrights; 
; 5 socklen_t msg_controllen; 
int msg_accrightslen; : 

int msg_flags; 


struct cmsghdr { 

socklen_t cmsg_len; 
(no equivalent) int cmsg_level; 
int cmsg_type; 


}; 


#define _SS_MAXSIZE 304 

#define _SS_ALIGNSIZE (sizeof (char*) ) 

#define _SS_PADISIZE (_SS_ALIGNSIZE - (sizeof(uint8_t) + 
sizeof (sa_family_t))) 

#define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(uint8_t) + 
sizeof(sa_family_t) + 
_SS_PADISIZE + _SS_ALIGNSIZE) ) 


#define _SS_MAXSIZE 304 
#define _SS_ALIGNSIZE (sizeof (char*) ) 
#define _SS_PADISIZE (_SS_ALIGNSIZE - 
sizeof (sa_family_t) ) 
#define _SS_PAD2SIZE (_SS_MAXSIZE — 
(sizeof (sa_family_t) + 
_SS_PADISIZE + 


Be SIA GNS TEED struct sockaddr_storage { 


struct sockaddr_storage { uines_e onsen) 


sa_family_t ss_family; 

char _ss_padl1[_SS_PAD1SIZE]; 
char* _ss_align; 

char _ss_pad2[_SS_PAD2SIZE]; 


sa_family_t ss_family; 

char _ss_pad1[_SS_PAD1SIZE]; 
char* _ss_align; 

char _ss_pad2[_SS_PAD2SI1ZE]; 


typedef int in_addr_t; 
(no equivalent) typedef unsigned short in_port_t; 


Usage Notes 


1. The struct sockaddr length field (sa_len and the address family specific equivalents: sun_len, sin_len, and sin6_len) is only provided for BSD 4.4 
compatibility. It is not necessary to use this field even when using BSD 4.4/UNIX 98 compatibility. The field is ignored on input addresses (like the 
local_address parameter on bind()) and will be properly set on output addresses (like the address parameter on accept()). 


2. The AF_TELEPHONY address sockaddr_tel and the AF_UNIX_CCSID address sockaddr_unc have not been updated with a length field equivalent to 
sa_len. If you use sa_len to set a length on these addresses, it will be ignored on input addresses and set to zero on output addresses. 


3. The structure sockaddr_storage is used to declare storage for any address family address. This structure is large enough and aligned for any 
protocol-specific structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the sockaddr_storage will always align 
with the family field of any protocol-specific structure. 


Note: The storage allocated is larger than 255 bytes so it's size should not be used for sa_len. The actual protocol-specific structure size should be used 
instead. 
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Sockets Network Functions 


The network functions and the Berkeley Resolver routines supported by the sockets APIs are: 


e@ dn_comp(Q) (Compress an expanded domain name) is used to compress an expanded domain name. 


e dn_comp_ts64Q (Compress an expanded domain name) is used to compress an expanded domain 
name. 


e dn_expand( (Expand a compressed domain name.) is used to expand a compressed domain name. 
e dn_findQ (Search for a compressed domain name from a list of previously compressed domain 
names) is used to search for an expanded domain name in a list of compressed domain names. 


e dn_find_ts64Q (Search for a compressed domain name from a list of previously compressed 


domain names) is used to search for an expanded domain name in a list of compressed domain 
names. 


e dn_skipnameQ( (Skip over a compressed domain name.) is used to skip over a compressed domain 
name in a DNS packet. 


e endhostent() (Close the nameserver database) is used to close the host database file. 

e endhostent_r(Q) (Close the nameserver database) is used to close the host database file. 

e endnetent() (Close the network database) is used to close the network database file. 

e endnetent_r() (Close the network database) is used to close the network database file. 

e endprotoent() (Close the protocol database) is used to close the protocols database file. 

e endprotoent_rQ (Close the protocol database) is used to close the protocol database file. 

e endservent() (Close the service database) is used to close the services database file. 

e endservent_r() (Close the service database) is used to close the service database file. 

e freeaddrinfo() (Free Address Information) frees one or more addrinfo structures returned by 
getaddrinfo(), along with any additional storage associated with those structures. 


e “eai_strerror() (Retrieve Address Information Runtime Error Message) retrieves a text string that 
describes a return value received from calling the getaddrinfo() or getnameinfo() APL.“& 
e getaddrinfo() (Get Address Information) translates the name of a service location or a service 


name and returns a set of socket addresses and associated information to be used in creating a 
socket with which to address the specified service.“ 


e gethostbyaddr() (Provide information about host given an Internet address) is used to retrieve 
information about a host. 


e gethostbyaddr_rQ (Provide information about host given an Internet address) is used to retrieve 
information about a host. 


e gethostbyname() (Provide information about host given a host name) is used to retrieve information 
about a host. 


e gethostbyname_rQ) (Provide information about host given a host name) is used to retrieve 
information about a host. 


e gethostent() (Get next host entry from the nameserver database) is used to retrieve information 
from the host database file. 


e gethostent_r(Q (Get next host entry from the nameserver database) is used to retrieve information 
from the host database file. 


#getnameinfo() (Get Name Information for Socket Address) translates a socket address to a node 
name and service location.%& 

getnetbyaddr() (Get information from the network database about a given internet address) is used 
to retrieve information about a network. 

getnetbyaddr_rQ (Get information from the network database about a given internet address) is 
used to retrieve information about a network. 

getnetbyname() (Get information from the network database about a given domain name) is used to 
retrieve information about a network. 

getnetbyname_r() (Get information from the network database about a given domain name) is used 
to retrieve information about a network. 

getnetent() (Get network entry from the network database) is used to retrieve network information 
from the network database file. 

getnetent_r() (Get network entry from the network database) is used to retrieve network 
information from the network database file. 


getprotobyname() (Get information regarding a protocol given the protocol name) is used to 
retrieve information about a protocol. 


getprotobyname_r() (Get information regarding a protocol given the protocol name) is used to 
retrieve information about a protocol. 


getprotobynumber() (Get information regarding a protocol given the protocol number) is used to 
retrieve information about a protocol. 


getprotobynumber_r() (Get information regarding a protocol given the protocol number) is used to 
retrieve information about a protocol. 

getprotoent() (Get next protocol entry in the protocol data base) is used to retrieve protocol 
information from the protocol database file. 

getprotoent_r() (Get next protocol entry in the protocol data base) is used to retrieve protocol 
information from the protocol database file. 

getservbyname() (Get port number for a given service name.) is used to retrieve information about 
services (the protocol being used by the service and the port number assigned for the service). 


getservbyname_r() (Get port number for a given service name.) is used to retrieve information 
about services: the protocol being used by the service and the port number assigned for the service. 


getservbyport() (Get service name given a port number) is used to retrieve information about a 
service assigned to a port number. 


getservbyport_r() (Get service name given a port number) is used to retrieve information about a 
service assigned to a port number. 

getservent() (Get next service entry from the service database) is used to retrieve information about 
services (the protocol being used by the service and the port number assigned for the service). 
getservent_r() (Get next service entry from the service database) is used to retrieve information 
about services: the protocol being used by the service and the port number assigned for the service. 
hstrerror() (Retrieve resolver error message.) is used to retrieve the text string that describes a 
resolver h_errno value. 

htonlQ (Convert a long (4 byte) integer from local host byte order to the network byte order) is used 
to convert a long (4-byte) integer from the local host byte order to standard network byte order. 


htons() (Convert a short (2 byte) integer from local host byte order to the network byte order) is 
used to convert a short (2-byte) integer from the local host byte order to standard network byte 


order. 


inet_addrQ) (Translate the full address from dotted decimal format to a 32-bit Internet address) is 
used to translate an Internet address from dotted decimal format to a 32-bit IP address. 

inet_Inaof() (Separate the local portion of an Internet address.) is used to extract the local host 
portion of an IP address. 

inet_makeaddr() (Formulate an Internet address that combines a network address with the local 
address of a host.) is used to generate a 32-bit IP address from the 32-bit network IP address and 
the local address of the host. 

inet_netof() (Separate the network portion of an Internet address.) is used to extract the network 
portion of an IP address. 

inet_network() (Translate the network portion of the address from dotted decimal format to a 32-bit 
Internet address) is used to translate an Internet address from dotted decimal format to a 32-bit 
network IP address, in which the host part of the IP address is set to zeros. 

inet_ntoa() (Translate from 32-bit Internet address to a dotted decimal format) is used to translate 
an Internet address from a 32-bit IP address to dotted decimal format. 

inet_ntoa_rQ) (Translate from 32-bit Internet address to a dotted decimal format) is used to translate 
an Internet address from a 32-bit IP address to dotted decimal format. 

#inet_ntop() (Convert IPv4 and IPv6 Addresses Between Binary and Text Form) converts a 
numeric address into a text string suitable for presentation.“& 


#inet_pton() (Convert IPv4 and IPv6 Addresses Between Text and Binary Form) converts an 
address in its standard text presentation form into its numeric binary form.*& 


ns_addr() (Translate a network services address from human readable format to a 12-byte 
hexadecimal address) is used to translate a network services address from human readable format to 
a 12-byte hexadecimal address. 

ns_ntoa() (Translate a network services address from a 12-byte address to a human readable 
format) is used to translate a network services address from a 12-byte address to a human readable 
format. 

ns_ntoa_rQ (Translate a network services address from a 12-byte address to a human readable 
format) is used to translate a network services address from a 12-byte address to a human readable 
format. 

ntohlQ (Convert a long (4 byte) integer from network byte order to the local host byte order) is used 
to convert a long (4-byte) integer from the standard network byte order to the local host byte order. 


ntohs() (Convert a short (2 byte) integer from network byte order to the local host byte order) is 
used to convert a short (2-byte) integer from the standard network byte order to the local host byte 
order. 

res_close() (Close a socket and reset the _res structure.) is used to reset the _res structure to the 
beginning defaults and close a socket that is opened as a result of the RES_STAYOPEN flag. 
res_findzonecutQ) (Find the enclosing zone and servers) queries name servers until it finds the 
enclosing zone and its master name servers for the specified domain name. 

res_hostalias(Q (Retrieve the host alias) looks up the specified name in the host aliases file specified 
by the environment variable HOSTALIASES. 

res_init() (Initialize _res structure for domain name server.) is used to initialize the _res structure 
for name resolution. 

res_mkquery() (Form a domain name query and place it in a buffer in memory.) is used to make 
standard query messages (DNS packets) for name servers. 


res_nclose() (Close socket and reset res structure) is used to reset the _res structure to the beginning 
defaults and close a socket that is opened as a result of the RES_STAYOPEN flag. 


res_ninit() (Initialize res structure) is used to initialize the _res structure for name resolution. 
res_nisourserver() (Check server address) looks up the specified server address in the ns_addr_list[] 
of the specified res structure. 


res_nmkquery() (Place domain query in buffer) is used to make standard query messages (DNS 
packets) for name servers. 


res_nmkupdate() (Construct an update packet) builds a dynamic update packet from the linked list 
of update records. 


res_nquery() (Send domain query) is used to interface to the server query mechanism. 


res_nquerydomain() (Send 2-string domain query) is used to interface to the server query 
mechanism. 


res_nsearch() (Search for domain name) is used to make a query message and wait for a response. 


res_nsendQ (Send buffered domain query or update) is used to send a query or update message to a 
name server and retrieve a response. 


res_nsendsigned() (Send authenticated domain query or update) is similar to res_nsend() but it uses 
the specified key to create a transaction signature (TSIG) to sign the query or update packet and to 
authenticate the response. 

res_nupdate() (Build and send dynamic updates) separates the linked list of update records into 
groups so that all records in a group will belong to a single zone on the nameserver. 


res_query() (Form a domain name query and send it to the domain name server.) is used to 
interface to the server query mechanism. 

res_search() (Search for a domain name from a list of domain names) is used to make a query 
message and wait for a response. 

res_sendQ (Send the query formed in res_mkquery to the domain name server.) is used to send a 
query or update message to a name server and retrieve a response. 

res_xlate() (Translate standard DNS packets between ASCII and EBCDIC) is used to translate a 
standard DNS packet between ASCII and EBCDIC. 

sethostent() (Open the nameserver database) is used to prepare for sequential access to the host 
database file. sethostent() opens the file and repositions the file marker to the beginning of the file. 
sethostent_r() (Open the nameserver database) is used in preparation for sequential access to the 
host database file. 

setnetent() (Open the network database) is used to prepare for sequential access to the network 
database file. 

setnetent_r() (Open the network database) is used in preparation for sequential access to the 
network database file. 

setprotoent() (Open the protocol database) is used to prepare for sequential access to the protocol 
database file. 

setprotoent_r() (Open the protocol database) is used in preparation for sequential access to the 
protocol database file. 

setservent() (Open the service database) is used to prepare for sequential access to the service 
database file. 


setservent_r() (Open the service database) is used in preparation for sequential access to the service 
database file. 


e _getlong() (Get long byte quantities from a byte stream) is used to retrieve an unsigned long byte 
quantity. 

e _getshortQ (Get short byte quantities from a byte stream.) is used to retrieve an unsigned short byte 
quantity. 

e _putlong( (Put long byte quantities into a byte stream.) is used to put an unsigned long byte 
quantity into a byte stream. 


e@ _putshort() (Put short byte quantities into a byte stream.) is used to put an unsigned short byte 
quantity into a byte stream. 


! TBM addition to the Berkeley Resolver Routines 
Note: These functions use header (include) files from the library QS YSINC, which is optionally installable. 


Make sure QSYSINC is installed on your system before using any of the functions. 
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dn_comp()--Compress Domain Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int dn_comp (unsigned char *expanded_domain_name, 
unsigned char *compressed_domain_name, 
int answer_buffer_length, 
unsigned char **domain_name_pointers, 
unsigned char **last_domain_name) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The dn_comp() function is used to compress an expanded domain name. 


Parameters 


expanded_domain_name 


(Input) The pointer to the expanded domain name. 


compressed_domain_name 


(Output) The pointer to where the compressed domain name will be stored. 


answer_buffer_length 


(Input) The size of the compressed_domain_name buffer. 


domain_name_pointers 


(Input) The pointer to an array of pointers to previously compressed domain names in the current 
message. 


last_domain_name 


(Input) The pointer to the end of the array specified by domain_name_pointers. 


Return Value 


dn_comp() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is the size of the compressed domain name. 


dn_comp() compresses the domain name pointed to by expanded_domain_name. The result is 
placed in compressed_domain_name. 


Error Conditions 


When the dn_comp() function fails, it does not set specific errno or h_errno values. An error occurs under 
the following conditions: 
e NULL pointer(s) passed to the function. 


e Invalid pointer(s) passed to the function. 


@ compressed_domain_name too small for the compressed domain name. 


Usage Notes 


1. domain_name_pointers[(0] points to the beginning of the DNS packet. The list of pointers ends with 
a NULL pointer. After domain_name_pointers[0] is initialized to the beginning of the packet and 
domain_name_pointers{(\] is initialized to NULL, dn_comp() updates the list each time it is called. 


2. dn_comp() calls dn_find() to attempt to locate the different parts of the domain name being 
compressed. 


3. dn_comp() expects EBCDIC data as input. The output from dn_comp() is also EBCDIC. 


Related Information 


e dn_expand(--Expand Domain Name 


e dn_findQ--Search for Compressed Domain Name 


e dn_skipname()--Skip over Compressed Domain Name 


API introduced: V3R1 
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dn_comp_ts64()--Compress Domain Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int dn_comp_ts64(unsigned char * __ptr64 expanded_domain_name, 
unsigned char * __ptr64 compressed_domain_name, 
int answer_buffer_length, 
unsigned char * __ptr64 * __ptr64 domain_name_pointers, 
unsigned char * __ptr64 * __ptr64 last_domain_name) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The dn_comp_ts64() function is used to compress an expanded domain name. dn_comp_ts64() differs from 
dn_comp() in that dn_comp_ts64() accepts 8-byte teraspace pointers. 


For a discussion of the parameters, authorities required, return values, and other related information, see 


dn_comp()--Compress Domain Name. 


Usage Notes 


All of the usage notes for dn_comp()--Compress Domain Name apply to dn_comp_ts64(). 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


dn_expand()--Expand Domain Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int dn_expand(unsigned char *message_pointer, 
unsigned char *end_of_message, 
unsigned char *compressed_domain_name, 
unsigned char *expanded_domain_name, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The dn_expand() function is used to expand a compressed domain name. 


Parameters 


message_pointer 


(Input) The pointer to the beginning of a DNS packet. 


end_of_message 
(Input) The pointer to the end of the DNS packet. 


compressed_domain_name 


(Input) The pointer to the compressed domain name within the DNS packet. 


expanded_domain_name 


(Output) The pointer to the expanded domain name. 


answer_buffer_length 


(Input) The size of the expanded_domain_name buffer. 


Return Value 


dn_expand() returns an integer. Possible values are: 


e -! (unsuccessful) 


e n (successful), where n is the size of the compressed domain name. 


The dn_expand() routine expands the domain name pointed to by compressed_domain_name. The 
result is placed in expanded_domain_name. 
Error Conditions 
When the dn_expand() function fails, it does not set specific errno or h_errno values. An error occurs under 
the following conditions: 
e NULL pointer(s) passed to the function. 
e Invalid pointer(s) passed to the function. 


@ expanded_domain_name too small for the expanded domain name. 


e end_of_message reached before the domain name could be expanded. 


Usage Notes 


1. The compressed domain name size is returned rather than the expanded domain name size because 
it is used to parse through the DNS packet. 


2. dn_expand() uses end_of_message to insure that it doesn't run past the end of the DNS packet. 


3. dn_expand() expects EBCDIC data as input. The output from dn_expand() is also EBCDIC. 


Related Information 


e dn_comp()--Compress Domain Name 


e dn _find(--Search for Compressed Domain Name 


e dn_skipname()--Skip over Compressed Domain Name 


API introduced: V3R1 
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dn_find()--Search for Compressed Domain 
Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int dn_find(unsigned char *expanded_domain_name, 
unsigned char *message_pointer, 
unsigned char **domain_name_pointers, 
unsigned char **last_domain_name) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The dn_find() function is used to search for an expanded domain name in a list of compressed domain 
names. 


Parameters 


expanded_domain_name 


(Input) The pointer to the expanded domain name. 


message_pointer_name 


(Input) A pointer to the DNS packet that contains the compressed names pointed to by the elements 
of domain_name_pointers. 


domain_name_pointers 


(Input) The pointer to an array of pointers to previously compressed names in the current message. 


last_domain_name 


(Input) The pointer to the end of the array of domain_name_pointers. 


Return Value 


dn_find() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is an offset into the message_pointer where domain name was found. 


Error Conditions 


When the dn_find() function fails, it does not set specific errno or h_errno values. An error occurs under 
the following conditions: 
e NULL pointer(s) passed to the function. 


e Invalid pointer(s) passed to the function. 


e Expanded domain name not found in the DNS packet. 


Usage Notes 


1. dn_find() locates an expanded name in an array of previously compressed names. 
2. Usually dn_find() is called from dn_comp() but can be called directly. 


3. dn_find() expects EBCDIC data as input. 


Related Information 


e dn_expand()--Expand Domain Name 


e dn_comp()--Compress Domain Name 


e dn_skipname()--Skip over Compressed Domain Name 


API introduced: V3R1 
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dn_find_ts64()--Search for Compressed 
Domain Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int dn_find_ts64(unsigned char * __ptr64 expanded_domain_name, 
unsigned char * __ptr64 message_pointer, 
unsigned char * __ptr64 * __ptr64 domain_name_pointers, 
unsigned char * __ptr64 * __ ptr64 last_domain_name) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The dn_find() function is used to search for an expanded domain name in a list of compressed domain 
names. dn_find_ts64() differs from dn_find() in that dn_find_ts64() accepts 8-byte teraspace pointers. 


For a discussion of the parameters, authorities required, return values, and other related information, see 
dn_find()--Search for Compressed Domain Name. 


Usage Notes 


All of the usage notes for dn_comp()--Compress Domain Name apply to dn_find_ts64(). 


API introduced: V5R1 
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dn_skipname()--Skip over Compressed Domain 
Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int dn_skipname (unsigned char *compressed_domain_name, 
unsigned char *end_of_message) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The dn_skipname() function is used to skip over a compressed domain name in a DNS packet. 


Parameters 


compressed_domain_name 


(Input) A pointer to a compressed domain name. 


end_of_message 
(Input) The pointer to the end of the message string. 


Return Value 


dn_skipname() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is the size of compressed_domain_name. 


Error Conditions 


When the dn_skipname() function fails, it does not set specific errno or h_errno values. An error occurs 
under the following conditions: 


e NULL pointer(s) passed to the function. 


e Invalid pointer(s) passed to the function. 


e end_of_message reached before the end of the compressed domain name. 


Usage Notes 


1. dn_skipname() skips over a compressed domain name in a DNS packet and returns the size of 
compressed_domain_name. 


2. dn_skipname() expects EBCDIC data as input. 


Related Information 


e dn _expand()--Expand Domain Name 


e dn_find()--Search for Compressed Domain Name 


e dn_comp()--Compress Domain Name 


API introduced: V3R1 
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endhostent()--Close Host Database 


Syntax 


#include <netdb.h> 


void endhostent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The endhostent() function is used to close the host database file. The file is opened by those functions that 
retrieve information about a host (for example, gethostent()). 


Authorities 


No authorization is required. 


Usage Notes 


1. 2 When the XOPEN_SOURCE macro defined to the value 520 or greater, the host file is always 
closed. When the _XOPEN_SOURCE macro is not so defined, the *& host file is not closed if a 
sethostent() with a nonzero parameter value was previously completed. 


2: ae iSeries Navigator or the & following CL commands can be used to access the host database 
ile: 
o ADDTCPHTE (Add TCP/IP Host Table Entry) 
oO RMVTCPHTE (Remove TCP/IP Host Table Entry) 
o CHGTCPHTE (Change TCP/IP Host Table Entry) 
Oo RNMTCPHTE (Rename TCP/IP Host Table Entry) 
oO MRGTCPHT (Merge TCP/IP Host Tables) 


3. Do not use the endhostent() function in a multithreaded environment. See the multithread 
alternative endhostent_r() function. 


4, 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endhostent() API is mapped to 
qso_endhostent98().%& 


Related Information 


e = XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface*® 


e gethostent()--Get Next Entry from Host Database 


e gethostbyname()--Get Host Information for Host Name 


e gethostbyaddr()--Get Host Information for IP Address 


e sethostent()--Open Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


endhostent_r()--Close Host Database 


Syntax 


#include <netdb.h> 


void endhostent_r(struct hostent_data 
*hostent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The endhostent_r() function is used to close the host database file. The file is opened by those functions 
that retrieve information about a host (for example, gethostent_r()). 


Parameters 

struct hostent_data *hostent_data_struct_addr (input) 
Specifies the pointer to the hostent_data structure, which is used to pass and preserve results 
between function calls. The field host_control_blk in the hostent_data structure must be initialized 


with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire hostent_data structure must be initialized to hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The endhostent_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct hostent_datadenoted by hostent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the endhostent_r() function fails, errno can be set to: 


[EINVAL] The hostent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure hostent_data. 


Usage Notes 


1. 2* When the XXOPEN_SOURCE macro defined to the value 520 or greater, the host file is always 
closed. When the _XOPEN_SOURCE macro is not so defined, the & host file will not be closed if 
a sethostent_r() call with a nonzero parameter value was previously done. 


2. #The iSeries Navigator or the *& following CL commands can be used to access the host database 
file: 


ADDTCPHTE (Add TCP/IP Host Table Entry) 
RMVTCPHTE (Remove TCP/IP Host Table Entry) 
CHGTCPHTE (Change TCP/IP Host Table Entry) 
RNMTCPHTE (Rename TCP/IP Host Table Entry) 
MRGTCPHT (Merge TCP/IP Host Tables) 


O 0 0 20 O 


3. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endhostent_r() API is mapped 
to gso_endhostent_r98().& 


Related Information 


e@ 2 XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface*& 


e gethostbyaddr_rQ--Get Host Information for IP Address 


e gethostbyname_r()--Get Host Information for Host Name 


e gethostent_rQ--Get Next Entry from Host Database 


e sethostent_r0--Open Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


endnetent()--Close Network Database 


Syntax 


#include <netdb.h> 


void endnetent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The endnetent() function is used to close the network database file. The file is opened by those functions 
that retrieve information about a network (for example, getnetent()). 


Usage Notes 


1. =* When the XOPEN_SOURCE macro defined to the value 520 or greater, the network file is 
always closed. When the _XOPEN_SOURCE macro is not so defined, the €€ network file is not 
closed if a setnetent() with a nonzero parameter value was previously completed. 


2. #The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 
Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 
Oo RMVNETTBLE (Remove Network Table Entry) 
3. Do not use the endnetent() function in a multithreaded environment. See the multithread alternative 


endnetent_r() function. 


4, 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endnetent() API is mapped to 
qso_endnetent98().*& 


Authorities 


No authorization is required. 


Related Information 


e@ = XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface*® 


@ getnetent()--Get Next Entry from Network Database 


@ setnetent()--Open Network Database 


@ getnetbyaddr()--Get Network Information for IP Address 


e@ getnetbyname()--Get Network Information for Domain Name 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


endnetent_r()--Close Network Database 


Syntax 


#include <netdb.h> 
int endnetent_r(struct netent_data 
*netent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The endnetent_r() function is used to close the network database file. The file is opened by those functions 
that retrieve information about a network (for example, getnetent_r()). 


Parameters 

struct netent_data *netent_data_struct_addr (input) 
Specifies the pointer to the netent_data structure, which is used to pass and preserve results 
between function calls. The field net_control_blk in the netent_data structure must be initialized 


with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire netent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The endnetent_r() function returns an integer. Possible values are: 


e -! (unsuccessful call) 


e 0 (successful call) 


The struct netent_datadenoted by netent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the endnetent_r() function fails, errno can be set to: 


[EINVAL] The netent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure netent_data. 


Usage Notes 


1. = When the XOPEN_ SOURCE macro defined to the value 520 or greater, the network file is 
always closed. When the _XOPEN_SOURCE macro is not so defined, the €€ network file will not 
be closed if a setnetent_r() call with a nonzero parameter value was previously done. 


2. #The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 


Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 
Oo RMVNETTBLE (Remove Network Table Entry) 


3. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endnetent_r() API is mapped to 
qso_endnetent_r98( )E 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e getnetent_r()--Get Next Entry from Network Database 


e@ getnetbyaddr_rQ--Get Network Information for IP Address 


e@ getnetbyname_r()--Get Network Information for Domain Name 


@ setnetent_r()--Open Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


endprotoent()--Close Protocol Database 


Syntax 


#include <netdb.h> 


void endprotoent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The endprotoent() function is used to close the protocols database file. The file is opened by those functions 
that retrieve information about a protocol (for example, getprotoent()). 


Authorities 


No authorization is required. 


Usage Notes 


1. 2 When the XOPEN_SOURCE macro defined to the value 520 or greater, the protocols file is 
always closed. When the _XOPEN_SOURCE macro is not so defined, the <i protocols file is not 
closed if a setprotoent() with a nonzero parameter value was previously completed. 


2. #The iSeries Navigator or the & following CL commands can be used to access the protocol 
database file: 
Oo WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 
Oo RMVPCLTBLE (Remove Protocol Table Entry) 
3. Do not use the endprotoent() function in a multithreaded environment. See the multithread 


alternative endprotoent_r() function. 


4. #When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endprotoent() API is mapped to 
gso_endprotoent98().& 


Related Information 


e@ = XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface** 


@ getprotoent()--Get Next Entry from Protocol Database 


@ setprotoent()--Open Protocol Database 


@ getprotobyname()--Get Protocol Information for Protocol Name 


@ getprotobynumber()--Get Protocol Information for Protocol Number 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


endprotoent_r()--Close Protocol Database 


Syntax 


#include <netdb.h> 
int endprotoent_r(struct protoent_data 
*protoent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The endprotoent_r() function is used to close the protocol database file. The file is opened by those 
functions that retrieve information about a protocol (for example, getprotoent_r()). 


Parameters 


struct protoent_data *protoent_data_struct_addr (input) 


Specifies the pointer to the protoent_data structure, which is used to pass and preserve results 
between function calls. The field proto_control_blk must be initialized with hexadecimal zeros 
before its initial use. If compatibility with other platforms is required, then the entire protoent_data 
structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The endprotoent_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct protoent_data denoted by protoent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the endprotoent_r() function fails, errno can be set to: 


[EINVAL] |The protoent_data structure was not properly initialized with hexadecimal zeros before 
initial use. For corrective action, see the description for structure protoent_data. 


Usage Notes 


1. 3* When the _XOPEN_SOURCE macro defined to the value 520 or greater, the protocols file is 
always closed. When the _XOPEN_SOURCE macro is not so defined, the € protocols file will not 
be closed if a setprotoent_r() call with a non-zero parameter value was previously done. 


2. #The iSeries Navigator or the *& following CL commands can be used to access the protocol 
database file: 


Oo WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 
Oo RMVPCLTBLE (Remove Protocol Table Entry) 


3. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endprotoent_r() API is mapped 
to gso_endprotoent_r98().& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface*& 


e getprotobynumber_r()--Get Protocol 


e@ getprotobyname_r()--Get Protocol Information for Protocol Name 


e@ getprotoent_r(Q--Get Next Entry from Protocol Database 


e setprotoent_r()--Open Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


endservent()--Close Service Database 


Syntax 


#include <netdb.h> 


void endservent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The endservent() function is used to close the services database file. The file is opened by those functions 
that retrieve information about services (for example, getservent()). 


Authorities 


No authorization is required. 


Usage Notes 


1. 2 When the XOPEN_SOURCE macro defined to the value 520 or greater, the services file is 
always closed. When the _XOPEN_SOURCE macro is not so defined, the «€ services file is not 
closed if a setservent() with a nonzero parameter value was previously completed. 


2. #The iSeries Navigator or the & following CL commands can be used to access the services 
database file: 
Oo WRKSRVTBLE (Work with Service Table Entries) 
o ADDSRVTBLE (Add Service Table Entry) 
Oo RMVSRVTBLE (Remove Service Table Entry) 
3. Do not use the endservent() function in a multithreaded environment. See the multithread 


alternative endservent_r() function. 


4. When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endservent() API is mapped to 
qso_endservent98( )& 


Related Information 


e = XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface**® 


@ getservent()--Get Next Entry from Service Database 


@ setservent()--Open Service Database 


@ getservbyname()--Get Port Number for Service Name 


@ getservbyport()--Get Service Name for Port Number 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


endservent_r()--Close Service Database 


Syntax 


#include <netdb.h> 
int endservent_r(struct servent_data 
*servent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The endservent_r() function is used to close the service database file. The file is opened by those functions 
that retrieve information about services (for example, getservent_r()). 


Parameters 


struct servent_data *servent_data_struct_addr (input) 


Specifies the pointer to the servent_data structure, which is used to pass and preserve results 
between function calls. The field serve_control_blk in the servent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire servent_data structure must initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The endservent_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct servent_datadenoted by servent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the endservent_r() function fails, errno can be set to: 


[EINVAL] | The servent_data structure was not properly initialized with hexadecimal zeros before initial 
use. For corrective action, see the description for structure servent_data. 


Usage Notes 


1. =* When the XOPEN_SOURCE macro defined to the value 520 or greater, the services file is 
always closed. When the _XOPEN_SOURCE macro is not so defined, the €€ services file will not 
be closed if a setservent_r() call with a non-zero parameter value was previously done. 


2. 2The iSeries Navigator or the *& following CL commands can be used to access the services 
database file: 


Oo WRKSRVTBLE (Work with Service Table Entries) 
o ADDSRVTBLE (Add Service Table Entry) 
Oo RMVSRVTBLE (Remove Service Table Entry) 


3. 2#*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the endservent_r() API is mapped 
to gso_endservent_r98( ) 8 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e@ getservbyname_r()--Get Port Number for Service Name 


e@ getservbyport_r(Q--Get Service Name for Port Number 


e@ getservent_r()--Get Next Entry from Service Database 


@ setservent_r()--Open Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


»freeaddrinfo()--Free Address Information 


Syntax 


#include <sys/socket.h> 
#include <netdb.h> 


void freeaddrinfo(struct addrinfo *ai); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The freeaddrinfo() function frees one or more addrinfo structures returned by getaddrinfoQ, along with any additional 


storage associated with those structures. If the ai_next field of the structure is not null, the entire list of structures is 
freed. 


Parameters 


ai 
(Input) The pointer to a struct addrinfo that was returned by getaddrinfo(). 


The structure struct addrinfo is defined in <netdb.h>. 


struct addrinfo { 


LT ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, 
*/ 
int ai_family; /* PF_xxx */ 
int ai_socktype; /* SOCK_xxx */ 
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 
socklen_t ai_addrlen; /* length of ai_addr */ 
char *ai_canonname; /* canonical name for nodename */ 
struct sockaddr *ai_addr; /* binary address */ 
struct addrinfo *ai_next; /* next structure in linked list */ 
}; 
Authorities 


No authorization is required. 


Usage Notes 


1. The freeaddrinfo(Q) API supports the freeing of arbitrary sublists of an addrinfo list originally returned by 
getaddrinfo(). 


Related Information 
e@ getaddrinfoQ--Get Address Information 
€ 


API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»gai_strerror()--Retrieve Address Information 
Runtime Error Message 


Syntax 


#include <sys/socket.h> 
#include <netdb.h> 


char *gai_strerror(int ecode); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The gai_strerror() function retrieves a text string that describes a return value received from calling the 


getaddrinfo() or getnameinfo() API. 


Parameters 


ecode 


(Input) The return value received from getaddrinfo() or getnameinfo(). 


Authorities 


No authorization is required. 


Return Value 


gai_strerror() returns a pointer to the return value text. 


Usage Notes 


1. gai_strerror() returns a pointer to the string. The null-terminated string is stored in the CCSID of 
the job. If the job is 65535 and the string is something other than EBCDIC single byte or EBCDIC 
mixed, the text is converted to the default job CCSID. 


2. If an ecode is specified for which there is no corresponding description, an Unknown Error string is 
returned. 


3. The null-terminated string addressed by the pointer returned is overlayed by subsequent invocations 
of the gai_strerror() API from within the same thread. 


Related Information 


e getaddrinfo()--Get Address Information 


e@ getnameinfo()--Get Name Information for Socket Address 


% 


API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»getaddrinfo()--Get Address Information 


Syntax 


#include <sys/socket.h> 
#include <netdb.h> 


int getaddrinfo(const char *nodename, const char *servname, 


const struct addrinfo *hints, 
struct addrinfo **res); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getaddrinfo() function translates the name of a service location (for example, a host name) and/or a service name 
and returns a set of socket addresses and associated information to be used in creating a socket with which to address 
the specified service. 


Parameters 


The nodename and servname parameters are either null pointers or pointers to null-terminated strings. One or both of 
these two parameters must be a non-null pointer. 


The format of a valid name depends on the protocol family or families. If a specific family is not given and the name 
could be interpreted as valid within multiple supported families, the implementation will attempt to resolve the name 
in all supported families and, in the absence of errors, one or more results shall be returned. 


nodename 


(Input) The pointer to the null-terminated character string that contains the descriptive name or address string 
for which the address information is to be retrieved. If the servname parameter is null, a nodename must be 
specified and the requested network-level address will be returned. If the nodename parameter is null, a 
servname must be specified and the requested service location will be assumed to be local to the caller. If the 
specified address family is AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names include host 
names. If the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, the permissable address 
string formats for the nodename parameter are specified as defined in inet_pton(). 


servname 


(Input) The pointer to the null-terminated character string that contains the descriptive name or numeric 
representation suitable for use with the address family or families for which the requested service information 
is to be retrieved. If nodename is not null, the requested service location is named by nodename; otherwise, 
the requested service location is local to the caller. If the specified address family is AF_INET, AF_INET®6, or 
AF_UNSPEC, the service can be specified as a string specifying a decimal port number. 


hints 


(Input) The pointer to a struct addrinfo. If the parameter hints is not null, it refers to a structure containing 
input values that may direct the operation by providing options and by limiting the returned information to a 
specific socket type, address family and/or protocol. In this hints structure every member other than ai_flags, 
ai_family, ai_socktype and ai_protocol must be zero or a null pointer. If hints is a null pointer, the behavior 
will be as if it referred to a structure containing the value zero for the ai_flags, ai_socktype and ai_protocol 


fields, and AF_UNSPEC for the ai_family field. 


The structure struct addrinfo is defined in <netdb.h>. 


struct addrinfo { 


int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, 
ef 

int ai_family; /* PF_xxx */ 

int ai_socktype; /* SOCK_xxx */ 

int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 

socklen_t ai_addrlen; /* length of ai_addr */ 

char *ai_canonname; /* canonical name for nodename */ 


struct sockaddr *ai_addr; /* binary address */ 
struct addrinfo *ai_next; /* next structure in linked list */ 


}; 


A value of AF_UNSPEC for ai_family means that the caller will accept any protocol family. A value of zero 
for ai_socktype means that the caller will accept any socket type. A value of zero for ai_protocol means that 
the caller will accept any protocol. 


If the caller handles only IPv4 and not IPv6, then the ai_family member of the hints structure should be set to 
PF_INET when getaddrinfo() is called. 


If the caller handles only TCP and not UDP, for example, then the ai_protocol member of the hints structure 
should be set to IPPROTO_TCP when getaddrinfo() is called. 


The ai_flags field to which hints parameter points must have the value zero or be the bitwise OR of one or 
more of the values AI_PASSIVE, AI CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, 
AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. 


The AI_PASSIVE flag in the ai_flags member of the hints structure specifies how to fill in the IP address 
portion of the socket address structure. If the AI_PASSIVE flag is specified, then the returned address 
information will be suitable for use in binding a socket for accepting incoming connections for the specified 
service (that is, a call to bindQ). In this case, if the nodename parameter is null, then the IP address portion of 
the socket address structure will be set to INADDR_ANY for an IPv4 address or INGADDR_ANY_INIT for 
an IPv6 address. If the AI_PASSIVE bit is not set, the returned address information will be suitable for a call 
to connect() (for a connection-oriented protocol) or for a call to connect(), sendto() or sendmsg() (for a 
connectionless protocol). In this case, if the nodename parameter is null, then the IP address portion of the 
socket address structure will be set to the loopback address. This flag is ignored if the nodename parameter is 
not null. 


If the flag AI CANONNAME is specified and the nodename parameter is not null, the function attempts to 
determine the canonical name corresponding to nodename (for example, if nodename is an alias or shorthand 
notation for a complete name). 


If the flag AI NUMERICHOST is specified then a non-null nodename string must be a numeric host address 
string. Otherwise an error of [EAI NONAME] is returned. This flag prevents any type of name resolution 
service (for example, the DNS) from being called. 


If the flag AI NUMERICSERV is specified then a non-null servname string must be a numeric port string. 
Otherwise an error [EAI_NONAME] is returned. This flag prevents any type of name resolution service (for 
example, NIS+) from being called. 


If the AI_V4MAPPED flag is specified along with an ai_family of AF_INETO®, then the caller will accept 
IPv4-mapped IPv6 addresses. That is, if no AAAA records are found then a query is made for A records and 
any found are returned as IPv4-mapped IPv6 addresses (ai_addrlen will be 28). The AI_V4MAPPED flag is 
ignored unless ai_family equals AF_INET6. 


The AI_ALL flag is used in conjunction with the AI_V4MAPPED flag, and is only used with an ai_family of 
AF_INET6. When AI_ALL is logically or'd with AI_LV4MAPPED flag then the caller will accept all 
addresses: IPv6 and IPv4-mapped IPv6. A query is first made for AAAA records and if successful, the IPv6 
addresses are returned. Another query is then made for A records and any found are returned as IPv4-mapped 


IPv6 addresses (ai_addrlen will be 28). This flag is ignored unless ai_family equals AF_INET6. 


If the AI_ ADDRCONHIG flag is specified then a query for AAAA records will occur only if the node has at 
least one IPv6 source address configured and a query for A records will occur only if the node has at least one 
IPv4 source address configured. The loopback address is not considered for this case as valid as a configured 
source address. 


The ai_socktype field to which argument hints points specifies the socket type for the service. If a specific 
socket type is not given (for example, a value of zero) and the service name could be interpreted as valid with 
multiple supported socket types, the implementation will attempt to resolve the service name for all supported 
socket types and, all successful results will be returned. A non-zero socket type value will limit the returned 
information to values with the specified socket type. 


res 


(Output) The pointer to a linked list of addrinfo structures, each of which specifies a socket address and 
information for use in creating a socket with which to use that socket address. The list will include at least one 
addrinfo structure. The ai_next field of each structure contains a pointer to the next structure on the list, or a 
null pointer if it is the last structure on the list. Each structure on the list includes values for use with a call to 
the socket() function, and a socket address for use with the connect() function or, if the AI_LPASSIVE flag was 
specified, for use with the bind() function. The fields ai_family, ai_socktype, and ai_protocol are usable as the 
arguments to the socket() function to create a socket suitable for use with the returned address. The fields 
ai_addr and ai_addrlen are usable as the arguments to the connect() or bind() functions with such a socket, 
according to the AI_PASSIVE flag. 


If nodename is not null, and if requested by the AI CANONNAME flag, the ai_canonname field of the first 
returned addrinfo structure points to a null-terminated string containing the canonical name corresponding to 
the input nodename; if the canonical name is not available, then ai_canonname refers to the argument 
nodename or a string with the same contents. The contents of the ai_flags field of the returned structures is 
undefined. 


All fields in socket address structures returned by getaddrinfo() that are not filled in through an explicit 
argument (for example, sin6_flowinfo and sin_zero) will be set to zero. 


Note: This makes it easier to compare socket address structures. 


Authorities 


Authorization of *R (allow access to the object) to the host aliases file specified by the HOSTALIASES environment 
variable. 


You also need *X authority to each directory in the path of the host aliases file. 


Return Value 


getaddrinfo() returns an integer. Possible values are: 


e 0 (successful) 


@ non-zero (unsuccessful) 


Error Conditions 


When getaddrinfo() fails, the error return value can be set to one of the following: 


[EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 
[EAI_BADFLAGS] The flags parameter had an invalid value. 

[EAI_FAIL] A non-recoverable error occurred when attempting to resolve the name. 

[EAI_FAMILY] The address family was not recognized. 

[EAILMEMORY] There was a memory allocation failure when trying to allocate storage for the return value. 


[EAI_NONAME] The name does not resolve for the supplied parameters. Neither nodename nor servname 
were passed. At least one of these must be passed. 


[EAL SERVICE] The service passed was not recognized for the specified socket type. 
[EAISOCKTYPE] | The intended socket type was not recognized. 


[EAISYSTEM] A system error occurred; the error code can be found in errno 


Usage Notes 


1. The freeaddrinfoQ) API must be used to free the addrinfo structures returned by getaddrinfo(). 


2. The gai_strerror() API may be used to retrieve an error message associated with one of the error return values 
described above. 


3. A job has a coded character set identifier (CCSID) and a default CCSID. The default CCSID is the same as the 
job CCSID unless the job CCSID specifies 65535, which requests that no database translation be performed. 
In this case, the default CCSID is set by the system based on the language ID in effect for the job. 


If the address information is retrieved from the domain name server, sockets converts the address information 
specified by the nodename and servname parameters from the default (CCSID) to ASCII before 
communicating with the domain name server. If the address information is retrieved from the host database 
file, no conversion is done on the node and service names specified by the nodename and servname 
parameters unless the CCSID of the job is something other than 65535. 


In addition, the canonical names for nodename returned in the addrinfo structures will be returned in the 
default CCSID of the job if they are obtained from the domain name server. For conversion to occur for the 
canonical names returned in the addrinfo structures when they are obtained from the host database file, you 
must use a job CCSID of something other than 65535. 


4. The host database file currently only supports IPv4 addresses. 


5. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro 
defined to the value 520 or greater, the getaddrinfo() API is mapped to getaddrinfo98(). 


Related Information 


e _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e bind()--Set a Local Address for the Socket 


e connect()--Establish Connection or Destination Address 


e freeaddrinfo()--Free Address Information 


@ gai_strerror()--Retrieve Address Information Runtime Error Message 


e gethostbyname()--Get Host Information for Host Name 


@ getnameinfo()--Get Name Information for Socket Address 


e@ getservbyname()--Get Port Number for Service Name 


@ getservbyport()--Get Service Name for Port Number 


@ inet_pton(Q--Convert IPv4 and IPv6 Addresses Between Text and Binary Form 


e sendto()--Send Data 


e sendmsg()--Send Data or Descriptors or Both 


e socket()--Create a Socket 


€ 
API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


gethostbyaddr()--Get Host Information for IP 
Address 


BSD 4.3 Syntax 


#include <netdb.h> 
struct hostent *gethostbyaddr(char *host_address, 


int address_length, 
int address_type) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


UNIX 98 Compatible Syntax 


#define _~XOPEN SOURCE 520 
#include <netdb.h> 


struct hostent *gethostbyaddr(const void *host_address, 
socklen_t address_length, 
int address_type) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


“4 


The gethostbyaddr() function is used to retrieve information about a host. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. *& 


Parameters 
host_address 
(Input) The pointer to a structure of type in_addr that contains the address of the host for which 


information is to be retrieved. 


address_length 
(Input) The length of the host_address. 


address_type 


(Input) The domain type of the host address. AF_INET is the only value for this parameter that is 
supported. 


Authorities 


No authorization is required. 


Return Value 


gethostbyaddr() returns a pointer. Possible values are: 


e NULL (unsuccessful) 


e p (successful), where p is a pointer to struct hostent, defined in <netdb.h>. 


struct hostent { 


char *h_ name; 
char *kh aliases; 
int h_addrtype; 
int h_length; 


char **kh addr_list; 


}; 
#define h_addr h_addr_list[0] 


h_name points to the character string that contains the name of the host. h_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the host. h_addrtype contains the address type of the host (for example, AF_INET). h_length 
contains the address length. h_addr_list is a pointer to a NULL-terminated list of pointers, each of which 
points to a network address for the host, in network byte order. Note that the array of address pointers 
points to structures of type in_addr defined in <netinet/in.h>. 


Error Conditions 


When gethostbyaddr() fails, h_errno (defined in <netdb.h>) can be set to one of the following: 


[HOST_NOT_FOUND] The host name specified by the host_address parameter was not found. 


[NO_DATA] The host name is a valid name, but there is no corresponding IP address. 
[NO_RECOVERY] An unrecoverable error has occurred. 


[TRY_AGAIN] The local server did not receive a response from an authoritative server. An 
attempt at a later time may succeed. 


Usage Notes 


1. The iSeries Navigator or the *& following CL commands can be used to access the host database 
file: 


o ADDTCPHTE (Add TCP/IP Host Table Entry) 
Oo RMVTCPHTE (Remove TCP/IP Host Table Entry) 
o CHGTCPHTE (Change TCP/IP Host Table Entry) 


Oo RNMTCPHTE (Rename TCP/IP Host Table Entry) 


O 


MRGTCPHT (Merge TCP/IP Host Tables) 


2. The pointer returned by gethostbyaddr() points to static storage that is overwritten on subsequent 
calls to the gethostbyaddr(), gethostbyname(), or gethostent() functions. 


3. There are two sources from which host information can be obtained: the domain name server, and 
the host database file. The path taken depends on whether an IP address is configured for a name 
server using #the iSeries Navigator or & option 12, Change TCP/IP domain information, on the 
Configure TCP/IP (CFGTCP) menu. 


Note: A person with a UNIX background would expect this information to exist in a file known as 
/etc/resolv.conf. If the IP address is found (indicating that the local network is a domain network), 
the gethostbyaddr() function attempts to query the domain name server for information about a 
host. If the query fails, the information is obtained from the host database file. If the name server IP 
address is not found (indicating that local network is a flat network), the host database file is used 
to obtain the host information. 


4. When host information is retrieved from the host database file, the opened file is only closed if a 
sethostent() with a nonzero parameter value was not previously done. 


5. If a sethostent() with a nonzero parameter value was previously done, gethostbyaddr(), when 
obtaining host information from the domain name server, communicates with the domain name 
server over a connection-oriented transport service (for example, TCP). Otherwise, gethostbyaddr() 
uses a connectionless transport service (for example, UDP). 


6. If the host information is obtained from the domain name server, the information is returned in the 


default coded character set identifier (CCSID) currently in effect for the job. (The default CCSID is 
the same as the job CCSID unless 65535 is requested, in which case the default CCSID is set based 
on the language ID of the job. See globalization for more information.) If the host information is 
retrieved from the host database file, the default CCSID of the job is not used. To request 
translation of the host information when it is retrieved from the host database file, you must use a 
job CCSID of something other than 65535. 


7. Address families are defined in <sys/socket.h>, and the in_addr structure is defined in 
<netinet/in.h>. 


8. Do not use the gethostbyaddr() function in a multithreaded environment. See the multithread 
alternative gethostbyaddr_r() function. 


9, 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the gethostbyaddr() API is mapped 
to gso_gethostbyaddr98().& 


Related Information 


@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e hstrerror()--Retrieve Resolver Error Message 


e@ res_hostalias()--Retrieve the host alias 


e gethostbyname()--Get Host Information for Host Name 


e gethostent()--Get Next Entry from Host Database 


e sethostent()--Open Host Database 


e endhostent()--Close Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


gethostbyaddr_r()--Get Host Information for IP 
Address 


BSD 4.3 Syntax 


#include <netdb.h> 

int gethostbyaddr_r(char *host_address, 
int address_length, 
int address_type, 


struct hostent *hostent_struct_addr, 
struct hostent_data *hostent_data_struct_addr) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netdb.h> 


int gethostbyaddr_r(const void *host_address, 
socklen_t address_length, 
int address_type, 


struct hostent *hostent_struct_addr, 
struct hostent_data *hostent_data_struct_addr) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: Yes 


= 


The gethostbyaddr_r() function is used to retrieve information about a host. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_ SOURCE macro. * 


Parameters 


host_address (input) 


Specifies the pointer to a structure of type in_addr that contains the address of the host for which 
information is to be retrieved. 


address_length (input) 
Specifies the length of the host_address. 


address_type (input) 


Specifies the domain type of the host address. Currently, AF_INET is the only value for this 
parameter that is supported. 


hostent_struct_addr (input/output) 


Specifies the pointer to a hostent structure where the results will be placed. All results must be 
referenced through this structure. 


hostent_data_struct_addr (input/output) 


Specifies the pointer to the hostent_data structure, which is used to pass and preserve results 
between function calls. The field host_control_blk in the hostent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire hostent_data structure must initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The gethostbyaddr_r() function returns an integer. Possible values are: 
e -1 (unsuccessful call) 
e 0 (successful call) 
The struct hostent denoted by hostent_struct_addr and struct hostent_datadenoted by 


hostent_data_struct_addr are both defined in <netdb.h>. The structure struct hostentis defined 
as: 


struct hostent [ 


char *h name; 
char *kh aliases; 
int h_addrtype; 
int h_length; 


char **kh addr_list; 


Ie 


#define h_addr h_addr_list[0] 


h_name points to the character string that contains the name of the host. h_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an 
alternative name for the host. h_addrtype contains the address type of the host (for example, 
AF_INET). h_length contains the size of an address in octets (for example, the size of an Internet 
address is 4 octets). h_addr_list is a pointer to a NULL-terminated list of pointers, each of which 
points to a network address (in network byte order) for the host. 


Error Conditions 


When the gethostbyaddr_r() function fails, h_errno (defined in <netdb.h>) can be set to: 


[HOST_NOT_FOUND] The host name specified by the host_address parameter was not found. 


[NO_DATA] The host name is a valid name, but there is no corresponding IP address. 
[NO_RECOVERY] An unrecoverable error has occurred. 
[TRY_AGAIN] The local server did not receive a response from an authoritative server. An 


attempt at a later time may succeed. 


When the gethostbyaddr_r() function fails, errno can be set to: 


[EINVAL] The hostent_data structure was not properly initialized with hexadecimal zeros before initial 
use. For corrective action, see the description for structure hostent_data. 


Usage Notes 


1. #The iSeries Navigator or the * following CL commands can be used to access the host database 
file: 


o ADDTCPHTE (Add TCP/IP Host Table Entry) 

Oo RMVTCPHTE (Remove TCP/IP Host Table Entry) 
o CHGTCPHTE (Change TCP/IP Host Table Entry) 
Oo RNMTCPHTE (Rename TCP/IP Host Table Entry) 
Oo MRGTCPHT (Merge TCP/IP Host Tables) 


2. There are two sources from which host information can be obtained: the domain name server and 
the host database file. The path taken depends on whether an IP address is configured for a name 
server using #the iSeries Navigator or & option 12, Change TCP/IP domain information, on the 
CFGTCP menu. 


Note: A person with a UNIX background would expect this information to exist in a file known as 
/etc/resolv.conf. If the IP address is found (indicating that the local network is a domain network), 
the gethostbyaddr_r() function will attempt to query the domain name server for information about 
a host. If the query fails, the information will be obtained from the host database file. If the name 


server IP address is not found (indicating that local network is a flat network), the host database file 
is used to obtain the host information. 


3. When the host information is obtained from the host database file, the file is opened and the host 
information is retrieved (if it exists) from the file. The file is then closed only if a sethostent_r() call 
with a non-zero parameter value was not previously done. 


4. If a sethostent_r() call with a non-zero parameter value was previously done, the gethostbyaddr_r() 
routine, when obtaining host information from the domain name server, will communicate with the 
domain name server over a connection-oriented transport service (for example, TCP). Otherwise, 
gethostbyaddr_r() will use a connectionless transport service (for example, UDP). 


5. If the host information is obtained from the domain name server, the information is returned in the 
default coded character set identifier (CCSID) currently in effect for the job. (The default CCSID is 
the same as the job CCSID unless 65535 is requested, in which case the default CCSID is set based 
on the language ID of the job. See the globalization topic for more information.) If the host 


information is retrieved from the host database file the default CCSID of the job is not used. To 
request translation of the host information when it is retrieved from the host database file, you must 
use a job CCSID of something other than 65535. 


6. Address families are defined in <sys/socket.h>, and the in_addr structure is defined in 
<netinet/in.h>. 


7. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the gethostbyaddr_r() API is 
mapped to qso_gethostbyaddr_r98().& 


Related Information 


e@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e hstrerror()--Retrieve Resolver Error Message 


res_hostalias(Q--Retrieve the host alias 


gethostbyname_r()--Get Host Information for Host Name 


e gethostent_r(--Get Next Entry from Host Database 


endhostent_r()--Close Host Database 


e sethostent_rQ--Open Host Database 


API introduced: V4R2 
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gethostbyname()--Get Host Information for 
Host Name 


BSD 4.3 Syntax 


#include <netdb.h> 


struct hostent *gethostbyname(char *host_name) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netdb.h> 


struct hostent *gethostbyname(const char *host_name) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 
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The gethostbyname() function is used to retrieve information about a host. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. *& 


Parameters 


host_name 


(Input) The pointer to the character string that contains the name of the host for which information 
is to be retrieved. 


Authorities 


Authorization of *R (allow access to the object) to the host aliases file specified by the HOSTALIASES 
environment variable. 


You also need *X authority to each directory in the path of the host aliases file. 


Return Value 


gethostbyname() returns a pointer. Possible values are: 
e NULL (unsuccessful) 


e p (successful), where p is a pointer to struct hostent. 


The structure struct hostent is defined in <netdb.h>. 


struct hostent { 


char *h name; 
char *kh aliases; 
int h_addrtype; 
int h_length; 


char *kh addr_list; 


}; 
#define h_addr h_addr_list[0] 


h_name points to the character string that contains the name of the host. h_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the host. h_addrtype contains the address type of the host (for example, AF_INET). h_length 
contains the address length. h_addr_list is a pointer to a NULL-terminated list of pointers, each of which 
points to a network address for the host, in network byte order. Note that the array of address pointers 
points to structures of type in_addr defined in <netinet/in.h>. 


Error Conditions 


When gethostbyname() fails, h_errno (defined in <netdb.h>) can be set to one of the following: 


[HOST_NOT_FOUND] | The host name specified by the host_name parameter was not found. 


[NO_DATA] The host name is a valid name, but there is no corresponding IP address. 
[NO_RECOVERY] An unrecoverable error has occurred. 
[TRY_AGAIN] The local server did not receive a response from an authoritative server. An 


attempt at a later time may succeed. 


When the gethostbyname() function fails, errno can be set to: 


[EACCES] Permission denied. The process does not have the appropriate privileges to the host aliases 
file specified by the HOSTALIASES environment variable. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the host database 
file: 


o ADDTCPHTE (Add TCP/IP Host Table Entry) 


Oo RMVTCPHTE (Remove TCP/IP Host Table Entry) 


O 


CHGTCPHTE (Change TCP/IP Host Table Entry) 


Oo RNMTCPHTE (Rename TCP/IP Host Table Entry) 


O 


MRGTCPHT (Merge TCP/IP Host Tables) 


2. The pointer returned by gethostbyname() points to static storage that is overwritten on subsequent 
calls to the gethostbyname(), gethostbyaddr(), or gethostent() functions. 


3. There are two sources from which host information can be obtained: the domain name server, and 
the host database file. The path taken depends on whether an IP address is configured for a name 
server using #the iSeries Navigator or *& option 12, Change TCP/IP domain information, on the 
Configure TCP/IP (CFGTCP) menu. 


Note: A person with a UNIX background would expect this information to exist in a file known as 
/etc/resolv.conf. 


If the IP address is found (indicating that the local network is a domain network), the 
gethostbyaddr() function attempts to query the domain name server for information about a host. If 
the query fails, the information is obtained from the host database file. If the name server IP 
address is not found (indicating that local network is a flat network), the host database file is used 
to obtain the address. 


4. If the host_name parameter does specify a domain qualified name, the gethostbyaddr() function 
appends a domain name to the specified host name, if possible. The domain name that is appended 
is configured using #the iSeries Navigator or  CFGTCP menu option 12, Change TCP/IP domain 
information. 


5. When the host information is obtained from the host database file, the file is opened and the host 
information is retrieved (if it exists) from the file. The file is then closed only if a sethostent() with 
a nonzero parameter value was not previously done. 


6. If a sethostent() with a nonzero parameter value was previously done, the gethostbyname() routine, 
when obtaining host information from the domain name server, communicates with the domain 
name server over a connection-oriented transport service (for example, TCP). Otherwise, 
gethostbyname() uses a connectionless transport service (for example, UDP). 


7. Ajob has a coded character set identifier (CCSID) and a default CCSID. The default CCSID is the 
same as the job CCSID unless the job CCSID specifies 65535, which requests that no database 
translation be performed. In this case, the default CCSID is set by the system based on the language 
ID in effect for the job. 


If the host information is retrieved from the domain name server, sockets converts the host name 
specified by the host_name parameter from the default (CCSID) to ASCII before communicating 
with the domain name server. If the host information is retrieved from the host database file, no 
conversion is done on the host name specified by the host_name parameter unless the CCSID of the 
job is something other than 65535. In addition, the host names returned in the hostent structure will 
be returned in the default CCSID of the job if they are obtained from the domain name server. For 
translation to occur for the host names returned in the hostent structure when they are obtained 
from the host database file, you must use a job CCSID of something other than 65535. 


8. Address families are defined in <sys/socket.h>, and the in_addr structure is defined in 
<netinet/in.h>. 


9. Do not use the gethostbyname() function in a multithreaded environment. See the multithread 
alternative gethostbyname_r() function. 


10. gethostbyname() will resolve local host aliases to a domain name which are then resolved with a 
query using DNS. See res_hostalias(Q) for more information on aliases. 


11. When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the gethostbyname() API is mapped 
to gso_gethostbyname98().%& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


hstrerror()--Retrieve Resolver Error Message 


e@ res_hostalias()--Retrieve the host alias 


e gethostbyaddr()--Get Host Information for IP Address 


gethostent()--Get Next Entry from Host Database 


e sethostent()--Open Host Database 


e endhostent()--Close Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


gethostbyname_r()--Get Host Information for 
Host Name 


BSD 4.3 Syntax 


#include <netdb.h> 
int gethostbyname_r(char *host_name, 


struct hostent *hostent_struct_addr, 
struct hostent_data *hostent_data_struct_addr) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netdb.h> 


int gethostbyname_r(const char *host_name, 


struct hostent *hostent_struct_addr, 
struct hostent_data *hostent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


% 


The gethostbyname_r() function is used to retrieve information about a host. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


host_name (input) 


Specifies the pointer to the character string that contains the name of the host for which information 
is to be retrieved. 


hostent_struct_addr (input/output) 


Specifies the pointer to a hostent structure where the results will be placed. All results must be 
referenced through this structure. 


hostent_data_struct_addr (input/output) 


Specifies the pointer to the hostent_data structure, which is used to pass and preserve results 
between function calls. The field host_control_blk in the hostent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire hostent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities: 


Authorization of *R (allow access to the object) to the host aliases file specified by the HOSTALIASES 
environment variable. 


You also need *X authority to each directory in the path of the host aliases file. 


Return Value 


The gethostbyname_r() function returns an integer. Possible values are: 
e -1 (unsuccessful call) 


e 0 (successful call) 


The struct hostent denoted by hostent_struct_addr and struct hostent_datadenoted by 
hostent_data_struct_addr are both defined in <netdb.h>. The structure struct hostentis defined as: 


struct hostent [ 


char *h name; 
char *kh aliases; 
int h_addrtype; 
int h_length; 


char **kh addr_list; 


]; 
#define h_addr h_addr_list[0] 


h_name points to the character string that contains the name of the host. h_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the host. h_addrtype contains the address type of the host (for example, AF_INET). h_length 
contains the size of an address in octets (for example, the size of an Internet address is 4 octets). h_addr_list 
is a pointer to a NULL-terminated list of pointers, each of which points to a network address (in network 
byte order) for the host. 


Error Conditions 


When the gethostbyname_r() function fails, h_errno (defined in <netdb.h>) can be set to: 


[HOST_NOT_FOUND] The host name specified by the host_name parameter was not found. 


[NO_DATA] The host name is a valid name, but there is no corresponding IP address. 
[NO_RECOVERY] An unrecoverable error has occurred. 
[TRY_AGAIN] The local server did not receive a response from an authoritative server. An 


attempt at a later time may succeed. 


When the gethostbyname_r() function fails, errno can be set to: 


[EACCES] Permission denied. The process does not have the appropriate privileges to the host aliases 
file specified by the HOSTALIASES environment variable. 


[EINVAL] The hostent_data structure was not initialized with hexadecimal zeros before initial use. 
For corrective action, see the description for structure hostent_data. 


Usage Notes 


1. 2The iSeries Navigator or the * following CL commands can be used to access the host database 
file: 


ADDTCPHTE (Add TCP/IP Host Table Entry) 
RMVTCPHTE (Remove TCP/IP Host Table Entry) 
CHGTCPHTE (Change TCP/IP Host Table Entry) 
RNMTCPHTE (Rename TCP/IP Host Table Entry) 
MRGTCPHT (Merge TCP/IP Host Tables) 


QO. OF Or Ov .O 


2. There are two sources from which host information can be obtained: the domain name server and 
the host database file. The path taken depends on whether an IP address is configured for a name 
server using #the iSeries Navigator or option 12, Change TCP/IP domain information, on the 
CFGTCP menu. 


Note: A person with a UNIX background would expect this information to exist in a file known as 
/etc/resolv.conf. If the IP address is found (indicating that the local network is a domain network), 
the gethostbyaddr_r() function will attempt to query the domain name server for information about 
a host. If the query fails, the information will be obtained from the host database file. If the name 
server IP address is not found (indicating that local network is a flat network), the host database file 


is used to obtain the address. 


3. If the host_name parameter does specify a domain qualified name, the gethostbyaddr_r() function 
will append a domain name to the specified host name, if possible. The domain name that will be 
appended is configured using #the iSeries Navigator or & CFGTCP menu option 12, Change 
TCP/IP domain information. 


4. When the host information is obtained from the host database file, the file is opened and the host 
information is retrieved (if it exists) from the file. The file is then closed only if a sethostent_r() call 
with a non-zero parameter value was not previously done. 


5. If a sethostent_r() call with a non-zero parameter value was previously done, the 
gethostbyname_r() routine, when obtaining host information from the domain name server, will 
communicate with the domain name server over a connection-oriented transport service (for 
example, TCP). Otherwise, gethostbyname_r() will use a connectionless transport service (for 
example, UDP). 


6. A job has a coded character set identifier (CCSID) and a default CCSID. The default CCSID is the 
same as the job CCSID unless the job CCSID specifies 65535, which requests that no database 
translation be performed. In this case, the default CCSID is set by the system based on the language 
ID in effect for the job. 


If the host information is retrieved from the domain name server, sockets converts the host name 
specified by the host_name parameter to ASCII before communicating with the domain name 
server. If the host information is retrieved from the host database file, no conversion is done on the 
host name specified by the host_name parameter unless the CCSID of the job is something other 
than 65535. In addition, host names returned in the hostent will be returned in the default CCSID of 
the job if they are obtained from the domain name server. For translation to occur for the host 
names returned in the hostent structure when they are obtained from the host database file, you 
must use a job CCSID of something other than 65535. 


7. Address families are defined in <sys/socket.h>, and the in_addr structure is defined in 
<netinet/in.h>. 


8. gethostbyname_r() will resolve local host aliases to a domain name which are then resolved with a 
query using DNS. See res_hostalias(Q) for more information on aliases. 


9, 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the gethostbyname_r() API is 
mapped to gso_gethostbyname_r98().%& 


Related Information 


e@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e hstrerror()--Retrieve Resolver Error Message 


e@ res_hostalias()--Retrieve the host alias 


e endhostent_r()--Close Host Database 


e gethostbyaddr_rQ--Get Host Information for IP Address 


e gethostent_rQ--Get Next Entry from Host Database 


e sethostent_rQ--Open Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


gethostent()--Get Next Entry from Host 
Database 


Syntax 


#include <netdb.h> 


struct hostent *gethostent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The gethostent() function is used to retrieve information from the host database file. When gethostent() is 
first called, the file is opened, and the first entry is returned. Each subsequent call to gethostent() results in 
the next entry in the file being returned. To close the file, use endhostent(). 


Authorities 


No authorization is required. 


Return Value 


gethostent() returns a pointer. Possible values are: 
e NULL (unsuccessful or end-of-file) 


e p (successful), where p is a pointer to struct hostent. 


The structure struct hostent is defined in <netdb.h>. 


struct hostent { 


char *x*h name; 
char *kh aliases; 
int h_addrtype; 
int h_length; 


char *kh addr_list; 


bi; 
#define h_addr h_addr_list[0] 
h_name points to the character string that contains the name of the host. h_aliases is a pointer to a 


NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the host. h_addrtype contains the address type of the host (for example, AF_INET). h_length 


contains the address length. h_addr_list is a pointer to a NULL-terminated list of pointers, each of which 
points to a network address for the host, in network byte order. Note that the array of address pointers 
points to structures of type in_addr defined in <netinet/in.h>. 


Usage Notes 
1. a iSeries Navigator or the *& following CL commands can be used to access the host database 
ile: 

o ADDTCPHTE (Add TCP/IP Host Table Entry) 
oO RMVTCPHTE (Remove TCP/IP Host Table Entry) 
Oo CHGTCPHTE (Change TCP/IP Host Table Entry) 
Oo RNMTCPHTE (Rename TCP/IP Host Table Entry) 
Oo MRGTCPHT (Merge TCP/IP Host Tables) 

2. The pointer returned by gethostent() points to static storage that is overwritten on subsequent calls 


to the gethostent(), gethostbyaddr(), or gethostbyname() functions. 


3. A coded character set identifier (CCSID) of 65535 requests that no database translation be 
performed. For translation to occur for the host names in the hostent structure, the job CCSID must 
be something other than 65535. 


4. Do not use the gethostent() function in a multithreaded environment. See the multithread alternative 
gethostent_r() function. 


5. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the gethostent() API is mapped to 
qso_gethostent9S( ) 5K 


Related Information 


e@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e gethostbyaddr()--Get Host Information for IP Address 


e gethostbyname()--Get Host Information for Host Name 


e endhostent()--Close Host Database 


e sethostent()--Open Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


gethostent_r()--Get Next Entry from Host 
Database 


Syntax 


#include <netdb.h> 
int gethostent_r(struct hostent 
*hostent_struct_addr, 
struct hostent_data 
*hostent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The gethostent_r() function is used to retrieve information from the host database file. When the 
gethostent_r() is first called, the file is opened, and the first entry is returned. Each subsequent call of 
gethostent_r() results in the next entry in the file being returned. To close the file, use endhostent_r(). 


Parameters 


struct hostent *hostent_struct_addr (input/output) 


Specifies the pointer to a hostent structure where the results will be placed. All results must be 
referenced through this structure. 


struct hostent_data *hostent_data_struct_addr (input/output) 


Specifies the pointer to the hostent_data structure, which is used to pass and preserve results 
between function calls. The field host_control_blk in the hostent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire hostent_data structure must be initialized to hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The gethostent_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct hostent denoted by hostent_struct_addr and struct hostent_datadenoted by 
hostent_data_struct_addr are both defined in <netdb.h>. The structure struct hostentis defined as: 


struct hostent [ 


char *h name; 
char *kh aliases; 
int h_addrtype; 
int h_length; 


char *k*kh addr_list; 


]; 
#define h_addr h_addr_list[0] 


h_name points to the character string that contains the name of the host. h_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the host. h_addrtype contains the address type of the host (for example, AF_INET). h_length 
contains the size of an address in octets (for example, the size of an Internet address is 4 octets). h_addr_list 
is a pointer to a NULL-terminated list of pointers, each of which points to a network address (in network 
byte order) for the host. 


Error Conditions 


When the gethostent_r() function fails, errno can be set to: 


[EINVAL] The hostent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure hostent_data. 


Usage Notes 


1. #The iSeries Navigator or the * following CL commands can be used to access the host database 
file: 


ADDTCPHTE (Add TCP/IP Host Table Entry) 
RMVTCPHTE (Remove TCP/IP Host Table Entry) 
CHGTCPHTE (Change TCP/IP Host Table Entry) 
RNMTCPHTE (Rename TCP/IP Host Table Entry) 
MRGTCPHT (Merge TCP/IP Host Tables) 


O 0 0 0 0 


2. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the host names returned in the hostent structure, the job 
CCSID must be something other than 65535. 


Related Information 
e gethostbyaddr_rQ--Get Host Information for IP Address 


e gethostbyname_r()--Get Host Information for Host Name 


e endhostent_r()--Close Host Database 


e sethostent_rQ--Open Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


»getnameinfo()--Get Name Information for 
Socket Address 


Syntax 


#include <sys/socket.h> 
#include <netdb.h> 


int getnameinfo(const struct sockaddr *sa, socklen_t salen, 
char *nodename, socklen_t nodenamelen, 
char *servname, socklen_t servnamelen, 
int flags); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getnameinfo() function translates a socket address to a node name and service location, all of which 
are defined as with getaddrinfo(Q). 


Parameters 


sa 


(Input) The pointer to a socket address structure to be translated. 


salen 


(Input) The length of the socket address structure pointed to by sa. 


nodename 


(Output) If the nodename parameter is non-NULL and the nodenamelen parameter is nonzero, then 
the nodename parameter must point to a buffer able to contain up to nodenamelen characters that 
will receive the node name as a null-terminated string. If the nodename parameter is NULL or the 
nodenamelen parameter is zero, the node name will not be returned. If the node's name cannot be 
located, the numeric form of the nodes address is returned instead of its name. 


nodenamelen 


(Input) The length of the buffer pointed to by nodename 


servname 


(Output) If the servname parameter is non-NULL and the servnamelen parameter is nonzero, then 
the servname parameter must point to a buffer able to contain up to servnamelen characters that 
will receive the service name as a null-terminated string. If the servname parameter is NULL or the 
servnamelen parameter is zero, the service name will not be returned. If the service name cannot be 


located, the numeric form of the service address (for example, its port number) is returned instead 
of its name. 


servnamelen 


(Input) The length of the buffer pointed to by servname 


flags 


(Input) A flag that changes the default actions of the function. By default the fully-qualified domain 
name (FQDN) for the host is returned, unless one of the following is true: 


o If the flag bit NILNOFQDN is set, only the nodename portion of the FQDN is returned for 
local hosts. 


o If the flag bit NIL.NUMERICHOST is set, the numeric form of the host's address is 
returned instead of its name, under all circumstances. 


o If the flag bit NL NAMEREQD is set, an error is returned if the host's name cannot be 
located. 


o If the flag bit NIL. NUMERICSERYV is set, the numeric form of the service address is 
returned (for example, its port number) instead of its name, under all circumstances. 


o If the flag bit NILDGRAM is set, this indicates that the service is a datagram service 
(SOCK_DGRAM). The default behavior is to assume that the service is a stream service 
(SOCK_STREAM). 


Authorities 


No authorization required. 


Return Value 


getnameinfo() returns an integer. Possible values are: 


e 0 (successful) 


@ non-zero (unsuccessful) 


On successful completion, function getnameinfo() returns the node and service names, if requested, in the 
buffers provided. The returned names are always null-terminated strings, and may be truncated if the actual 
values are longer than can be stored in the buffers provided. If the returned values are to be used as part of 
any further name resolution (for example, passed to getaddrinfoQ, callers must either provide buffers large 
enough to store any result possible on the system or must check for truncation and handle that case 
appropriately. 


Error Conditions 

When getnameinfo() fails, the error return value can be set to one of the following: 
[EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 
[EAI_BADFLAGS] The flags parameter had an invalid value. 


[EAI_FAIL] A non-recoverable error occurred. 


[EAI_FAMILY] The address family was not recognized or the address length was invalid for the 
specified family. 


[EAIMEMORY] There was a memory allocation failure. 


[EAI_NONAME] The name does not resolve for the supplied parameters. NI. NAMEREQD is set 
and the host's name cannot be located, or both nodename and servname were null. 


[EAL SYSTEM] A system error occurred; the error code can be found in errno 


Usage Notes 
1. The nodename and servname parameters cannot both be NULL. 


2. The gai_strerror() API may be used to retrieve an error message associated with one of the error 
return values described above. 


3. If the node and service information is obtained from the domain name server, the information is 
returned in the default coded character set identifier (CCSID) currently in effect for the job. (The 
default CCSID is the same as the job CCSID unless 65535 is requested, in which case the default 
CCSID is set based on the language ID of the job. See Globalization for more information.) If the 
node and service information is retrieved from the host database file, the default CCSID of the job 
is not used. To request conversion of the host information when it is retrieved from the host 
database file, you must use a job CCSID of something other than 65535. 


4. When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getnameinfo() API is mapped to 
getnameinfo98(). 


Related Information 


e _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


getaddrinfo()--Get Address Information 


gai_strerror()--Retrieve Address Information Runtime Error Message 


e gethostbyaddr()--Get Host Information for IP Address 


@ getservbyport()--Get Service Name for Port Number 


@ inet_ntopQ--Convert IPv4 and IPv6 Addresses Between Binary and Text Form 


% 


API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


getnetbyaddr()--Get Network Information for IP 
Address 


BSD 4.3 Syntax 


#include <netdb.h> 


struct netent *getnetbyaddr(long network_address, 
int address_type) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netdb.h> 


struct netent *getnetbyaddr (uint32_t network_address, 
int address_type) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


“4 


The getnetbyaddr() function is used to retrieve information about a network. The information is retrieved 
from the network database file. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_ SOURCE macro. *& 


Parameters 


network_address 


(Input) The 32-bit network IP address for which information is to be retrieved. 


address_type 
(Input) An integer that indicates the type of network_address. 


Authorities 


No authorization is required. 


Return Value 


getnetbyaddr() returns a pointer. Possible values are: 
e@ NULL (unsuccessful) 


e p (successful), where p is a pointer to struct netent. 


The structure struct netent is defined in <netdb.h>. 


struct netent { 


char *n name; 
char k*xn aliases; 
int n_addrtype; 


unsigned long n_net; 


}; 


n_name points to the character string that contains the name of the network. n_aliases is a pointer to a 
NULL-terminated array of alternate names for the network. n_addrtype contains the address type of the 
network. n_net is the 32-bit network address (an IP address with host part set to zero). 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 


Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 


Oo RMVNETTBLE (Remove Network Table Entry) 


2. The pointer returned by getnetbyaddr() points to static storage that is overwritten on subsequent 
calls to the getnetbyaddr(), getnetbyname(), or getnetent() functions. 


3. When the network information is obtained from the network database file, the file is opened and the 
network information is retrieved (if it exists) from the file. The file is then closed only if a 
setnetent() with a nonzero parameter value was not previously done. 


4. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the network names returned in the netent structure, the 
job CCSID must be something other than 65535. 


5. Do not use the getnetbyaddr() function in a multithreaded environment. See the multithread 
alternative getnetbyaddr_r() function. 


6. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getnetbyaddr() API is mapped 
to gso_getnetbyaddr98().*& 


Related Information 


e@ = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e@ getnetbyname()--Get Network Information for Domain Name 


e@ getnetent()--Get Next Entry from Network Database 


@ setnetent()--Open Network Database 


e endnetent()--Close Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getnetbyaddr_r()--Get Network Information for 
IP Address 


Syntax 


#include <netdb.h> 


int getnetbyaddr_r(long network_address, 
int address_type, 
struct netent *netent_struct_addr, 
struct netent_data 
*netent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


A program uses the getnetbyaddr_r() function to retrieve information about a network. The information is 
retrieved from the network database file. 


Parameters 


long network_address (input) 


Specifies the 32-bit network IP address for which information is to be retrieved. 


int address_type (input) 


Specifies an integer that indicates the type of network_address. 


struct netent *netent_struct_addr (input/output) 


Specifies the pointer to a netent structure where the results will be placed. All results must be 
referenced through this structure. 


struct netent_data *netent_data_struct_addr (input/output) 


Specifies the pointer to the netent_data structure, which is used to pass and preserve results 
between function calls. The field net_control_blk in the netent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire netent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The getnetbyaddr_r() function returns a integer. Possible values are: 
e -1 (unsuccessful call) 


e@ 0 (successful call) 


The struct netent denoted by netent_struct_addr and struct netent_datadenoted by 
netent_data_struct_addr are both defined in <netdb.h>. The structure struct netentis defined as: 


struct netent [ 


char *n name; 
char k*xn aliases; 
int n_addrtype; 
unsigned long n_net; 


]; 


n_name points to the character string that contains the name of the network. n_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the network. n_addrtype contains the address type of the network (that is, AF_INET). m_net is the 
32-bit network address (that is, an IP address in network byte order with host part set to zero). 


Error Conditions 


When the getnetbyaddr_r() function fails, errno can be set to: 


[EINVAL] The netent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure netent_data. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 


Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 
Oo RMVNETTBLE (Remove Network Table Entry) 


2. When the network information is obtained from the network database file, the file is opened and the 
network information is retrieved (if it exists) from the file. The file is then closed only if a 
setnetent_r() call with a non-zero parameter value was not previously done. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the network names returned in the netent structure, the 
job CCSID must be something other than 65535. 


Related Information 


e@ getnetent_rQ--Get Next Entry from Network Database 


e@ getnetbyname_r()--Get Network Information for Domain Name 


e setnetent_r(--Open Network Database 


e@ endnetent_r()--Close Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getnetbyname()--Get Network Information for 
Domain Name 


BSD 4.3 Syntax 


#include <netdb.h> 
struct netent *getnetbyname(char *network_name) 
Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netdb.h> 


struct netent *getnetbyname(const char *network_name) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


“s 


The getnetbyname() function is used to retrieve information about a network. The information is retrieved 
from the network database file. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. *& 


Parameters 


network_name 


(Input) The pointer to the character string that contains the name of the network for which 
information is to be retrieved. 


Authorities 


No authorization is required. 


Return Value 


getnetbyname() returns a pointer. Possible values are: 
e NULL (unsuccessful) 


e p (successful), where p is a pointer to struct netent. 


The structure struct netent is defined in <netdb.h>. 


struct netent { 


char *n name; 
char k*xn aliases; 
int n_addrtype; 
unsigned long n_net; 


be 


n_name points to the character string that contains the name of the network. n_aliases is a pointer to a 
NULL-terminated array of alternate names for the network. n_addrtype contains the address type of the 
network. n_net is the 32-bit network address (an IP address with host part set to zero). 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 


Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 


oO RMVNETTBLE (Remove Network Table Entry) 


2. The pointer returned by getnetbyname() points to static storage that is overwritten on subsequent 
calls to the getnetbyname(), getnetbyaddr(), or getnetent() functions. 


3. When the network information is obtained from the network database file, the file is opened and the 
network information is retrieved (if it exists) from the file. The file is then closed only if a 
setnetent() with a nonzero parameter value was not previously done. 


4. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the network name specified by the network_name 
parameter, and for the network names returned in the netent structure, the job CCSID must be 
something other than 65535. 


5. Do not use the getnetbyname() function in a multithreaded environment. See the multithread 
alternative getnetbyname_r() function. 


6. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getnetbyname() API is mapped 
to gso_getnetbyname98().%& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e@ getnetbyaddr()--Get Network Information for IP Address 


e@ getnetent()--Get Next Entry from Network Database 


e setnetent()--Open Network Database 


e endnetent()--Close Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getnetbyname_r()--Get Network Information for 
Domain Name 


Syntax 


#include <netdb.h> 
int getnetbyname_r(char *network_name, 
struct netent *netent_struct_addr, 
struct netent_data 
*netent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getnetbyname_r() function is used to retrieve information about a network. The information is retrieved 
from the network database file. 


Parameters 


char *network_name (input/output) 


Specifies the pointer to the character string that contains the name of the network for which 
information is to be retrieved. 


struct netent *netent_struct_addr (input/output) 


Specifies the pointer to a netent structure where the results will be placed. All results must be 
referenced through this structure. 


struct netent_data *netent_data_struct_addr (input/output) 


Specifies the pointer to the netent_data structure, which is used to pass and preserve results 
between function calls. The field net_control_blk in the netent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire netent_data structure must initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The getnetbyname_r() function returns an integer. Possible values are: 
e -1 (unsuccessful call) 


e@ 0 (successful call) 


The struct netent denoted by netent_struct_addr and struct netent_datadenoted by 
netent_data_struct_addr are both defined in <netdb.h>. The structure struct netentis defined as: 


struct netent [ 


char *n name; 
char k*xn aliases; 
int n_addrtype; 


unsigned long n_net; 


liz 


n_name points to the character string that contains the name of the network. n_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the network. n_addrtype contains the address type of the network (that is, AF_INET). m_net is the 
32-bit network address (that is, an IP address in network byte order with host part set to zero). 


Error Conditions 


When the getnetbyname_r() function fails, errno can be set to: 


[EINVAL] The netent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure netent_data. 


Usage Notes 


1. #The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 


Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 
Oo RMVNETTBLE (Remove Network Table Entry) 


2. When the network information is obtained from the network database file, the file is opened and the 
network information is retrieved (if it exists) from the file. The file is then closed only if a 
setnetent_r() call with a non-zero parameter value was not previously done. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the network name specified by the network_name 
parameter, and for the network names returned in the netent structure, the job CCSID must be 
something other than 65535. 


Related Information 
@ getnetent_r()--Get Next Entry from Network Database 


e@ getnetbyaddr_rQ--Get Network Information for IP Address 


@ setnetent_r0--Open Network Database 


e@ endnetent_r()--Close Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getnetent()--Get Next Entry from Network 
Database 


Syntax 


#include <netdb.h> 


struct netent *getnetent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The getnetent() function is used to retrieve network information from the network database file. When 
getnetent() is first called, the file is opened, and the first entry is returned. Each subsequent call to 
getnetent() results in the next entry in the file being returned. To close the file, use endnetent(). 


Authorities 


No authorization is required. 


Return Value 


getnetent() returns a pointer. Possible values are: 
e NULL (unsuccessful or end-of-file) 


e p (successful), where p is a pointer to struct netent. 


The structure struct netent is defined in <netdb.h>. 


struct netent { 


char *n name; 
char k*xn aliases; 
int n_addrtype; 
unsigned long n_net; 


}; 


n_name points to the character string that contains the name of the network. n_aliases is a pointer to a 
NULL-terminated array of alternate names for the network. n_addrtype contains the address type of the 
network. n_net is the 32-bit network address (an IP address with host part set to zero). 


Usage Notes 
1. #The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 
Oo WRKNETTBLE (Work with Network Table Entries) 


o ADDNETTBLE (Add Network Table Entry) 


oO RMVNETTBLE (Remove Network Table Entry) 


2. The pointer returned by getnetent() points to static storage that is overwritten on subsequent calls to 
the getnetent(), getnetbyaddr(), or getnetbyname() functions. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the network names returned in the netent structure, the 
job CCSID must be something other than 65535. 


4. Do not use the getnetent() function in a multithreaded environment. See the multithread alternative 
getnetent_r() function. 


5. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getnetent() API is mapped to 
qso_getnetent98/( ) 5K 


Related Information 


e@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e@ getnetbyaddr()--Get Network Information for IP Address 


e@ getnetbyname()--Get Network Information for Domain Name 


e endnetent()--Close Network Database 


e setnetent()--Open Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getnetent_r()--Get Next Entry from Network 
Database 


Syntax 


#include <netdb.h> 
int getnetent_r(struct netent *netent_struct_addr, 
struct netent_data 
*netent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getnetent_r() function is used to retrieve network information from the network database file. When the 
getnetent_r() is first called, the file is opened, and the first entry is returned. Each subsequent call of 
getnetent_r() results in the next entry in the file being returned. To close the file, use endnetent_r(). 


Parameters 


struct netent *netent_struct_addr (input/output) 


Specifies the pointer to a netent structure where the results will be placed. All results must be 
referenced through this structure. 


struct netent_data *netent_data_struct_addr (input/output) 


Specifies the pointer to the netent_data structure, which is used to pass and preserve results 
between function calls. The field net_control_blk in the netent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire netent_data structure must initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The getnetent_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct netent, denoted by netent_struct_addr and struct netent_datadenoted by 
netent_data_struct_addr are both defined in <netdb.h>. The structure struct netentis defined as: 


struct netent [ 


char *n name; 
char *k*xn aliases; 
int n_addrtype; 
unsigned long n_net; 


l; 
n_name points to the character string that contains the name of the network. n_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 


name for the network. n_addrtype contains the address type of the network (that is, AF_INET). m_net is the 
32-bit network address (that is, an IP address in network byte order with host part set to zero). 


Error Conditions 


When the getnetent_r() function fails, errno can be set to: 


[EINVAL] The netent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure netent_data. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 


Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 
Oo RMVNETTBLE (Remove Network Table Entry) 


2. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the network names returned in the netent structure, the 
job CCSID must be something other than 65535. 


Related Information 


e@ getnetbyaddr_rQ--Get Network Information for IP Address 


e@ getnetbyname_r()--Get Network Information for Domain Name 


e setnetent_r()--Open Network Database 


e endnetent_r()--Close Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getprotobyname()--Get Protocol Information for 
Protocol Name 


BSD 4.3 Syntax 


#include <netdb.h> 


struct protoent *getprotobyname(char *protocol_name) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netdb.h> 


struct protoent *getprotobyname(const char *protocol_name) 


Service Program Name: QSOSRV2 
Default Public Authority:*USE 


Threadsafe: No; see Usage Notes. 


“s 


The getprotobyname() function is used to retrieve information about a protocol. The information is 
retrieved from the protocol database file. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_ SOURCE macro. *& 


Parameters 


protocol_name 


(Input) The pointer to the character string that contains the name of the protocol for which 
information is to be retrieved. 


Authorities 


No authorization is required. 


Return Value 


getprotobyname() returns a pointer. Possible values are: 
e NULL (unsuccessful) 


e p (successful), where p is a pointer to struct protoent 


The structure struct protoent is defined in <netdb.h>. 


struct protoent { 


char *p name; 
char **kp aliases; 
int p_proto; 


}; 


p_name points to the character string that contains the name of the protocol. p_aliases is a pointer to a 
NULL-terminated array of alternate names for the protocol. p_proto is the protocol number. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the protocol 
database file: 


Oo WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 


Oo RMVPCLTBLE (Remove Protocol Table Entry) 


2. The pointer returned by getprotobyname() points to static storage that is overwritten on subsequent 
calls to the getprotobyname(), getprotobynumber(), or getprotoent() functions. 


3. When the protocol information is obtained from the protocol database file, the file is opened and 
the protocol information is retrieved (if it exists) from the file. The file is then closed only if a 
setprotoent() with a nonzero parameter value was not previously done. 


4. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol name specified by the protocol_name 
parameter, and for the protocol names returned in the protoent structure, the job CCSID must be 
something other than 65535. 


5. Do not use the getprotobyname() function in a multithreaded environment. See the multithread 
alternative getprotobyname_zr() function. 


6. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getprotobyname() API is 
mapped to gso_getprotobyname98().%& 


Related Information 


e *=_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface** 


@ getprotobynumber()--Get Protocol Information for Protocol Number 


e@ getprotoent()--Get Next Entry from Protocol Database 


@ setprotoent()--Open Protocol Database 


e endprotoent()--Close Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getprotobyname_r()--Get Protocol Information 
for Protocol Name 


Syntax 


#include <netdb.h> 
int getprotobyname_r(char *protocol_name, 
struct protoent 
*protoent_struct_addr, 
struct protoent_data 
*protoent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getprotobyname_r() function is used to retrieve information about a protocol. The information is 
retrieved from the protocol database file. 


Parameters 


char *protocol_name (input) 


Specifies the pointer to the character string that contains the name of the protocol for which 
information is to be retrieved. 


struct protoent *protoent_struct_addr (input/output) 


Specifies the pointer to a protoent structure where the results will be placed. All results must be 
referenced through this structure. 


struct protoent_data *protoent_data_struct_addr (input/output) 


Specifies the pointer to the protoent_data structure, which is used to pass and preserve results 
between function calls. The field proto_control_blk in the protoent_data structure must be 
initialized with hexadecimal zeros before its initial use. If compatibility with other platforms is 
required, then the entire protoent_data structure must be initialized with hexadecimal zeros before 
initial use. 


Authorities 


No authorization is required. 


Return Value 


The getprotobyname_r() returns an integer. Possible values are: 
e -1 (unsuccessful call) 


e@ 0 (successful call) 


The struct protoent denoted by protoent_struct_addr and struct protoent_data denoted by 
protoent_data_struct_addr are both defined in <netdb.h>. The structure struct protoentis defined as: 


struct protoent [ 


char *p name; 
char *xp aliases; 
int p_proto; 
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p_name points to the character string that contains the name of the protocol. p_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the protocol. p_proto is the protocol number. 


Error Conditions 


When the getprotobyname_r() function fails, errno can be set to: 


[EINVAL] The protoent_data structure was not properly initialized with hexadecimal zeros before 
initial use. For corrective action, see the description for structure protoent_data. 


Usage Notes 


1. The iSeries Navigator or the * following CL commands can be used to access the protocol 
database file: 


oO WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 
Oo RMVPCLTBLE (Remove Protocol Table Entry) 


2. When the protocol information is obtained from the protocol database file, the file is opened and 
the protocol information is retrieved (if it exists) from the file. The file is then closed only if a 
setprotoent_r() call with a non-zero parameter value was not previously done. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol name specified by the protocol_name 
parameter, and for the protocol names returned in the protoent structure, the job CCSID must be 
something other than 65535. 


Related Information 
@ getprotobynumber_r()--Get Protocol 


@ getprotoent_r()--Get Next Entry from Protocol Database 


@ setprotoent_r(Q--Open Protocol Database 


e endprotoent_r()--Close Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getprotobynumber()--Get Protocol Information 
for Protocol Number 


Syntax 


#include <netdb.h> 


struct protoent 
*getprotobynumber (int protocol_number) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The getprotobynumber() function is used to retrieve information about a protocol. The information is 
retrieved from the protocol database file. 


Parameters 


protocol_number 


(Input) The protocol number for which information is to be retrieved. 


Authorities 


No authorization is required. 


Return Value 


getprotobynumber() returns a pointer. Possible values are: 
e@ NULL (unsuccessful) 


e p (successful), where p is a pointer to struct protoent. 


The structure struct protoent is defined in <netdb.h>. 


struct protoent { 
char *p_ name; 
char *xp aliases; 
int p_proto; 

}i 


p_name points to the character string that contains the name of the protocol. p_aliases is a pointer to a 
NULL-terminated array of alternate names for the protocol. p_proto is the protocol number. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the protocol 
database file: 


Oo WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 


Oo RMVPCLTBLE (Remove Protocol Table Entry) 


2. The pointer returned by getprotobynumber() points to static storage that is overwritten on 
subsequent calls to the getprotobynumber(), getprotobyname(), or getprotoent() functions. 


3. When the protocol information is obtained from the protocol database file, the file is opened and 
the protocol information is retrieved (if it exists) from the file. The file is then closed only if a 
setprotoent() with a nonzero parameter value was not previously done. 


4. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol names returned in the protoent structure, the 
job CCSID must be something other than 65535. 


5. Do not use the getprotobynumber() function in a multithreaded environment. See the multithread 
alternative getprotobynumber() function. 


6. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getprotobynumber() API is 
mapped to gso_getprotobynumber98().%& 


Related Information 


e@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e@ getprotobyname()--Get Protocol Information for Protocol Name 


e@ getprotoent()--Get Next Entry from Protocol Database 


@ setprotoent()--Open Protocol Database 


e endprotoent()--Close Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getprotobynumber_r()--Get Protocol 
Information for Protocol Number 


Syntax 


#include <netdb.h> 


int getprotobynumber_r(int protocol_number, 
struct protoent 
*protoent_struct_addr, 
struct protoent_data 
*protoent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getprotobynumber_r() function is used to retrieve information about a protocol. The information is 
retrieved from the protocol database file. 


Parameters 


int protocol_number (input) 


Specifies the protocol number for which information is to be retrieved. 


struct protoent *protoent_struct_addr (input/output) 


Specifies the pointer to a protoent structure where the results will be placed. All results must be 
referenced through this structure. 


struct protoent_data *protoent_data_struct_addr (input/output) 


Specifies the pointer to the protoent_data structure, which is used to pass and preserve results 
between function calls. The field proto_control_blk in the protoent_data structures must be 
initialized with hexadecimal zeros before its initial use. If compatibility with other platforms is 
required, then the entire protoent_data structure must be initialized with hexadecimal zeros before 
initial use. 


Authorities 


No authorization is required. 


Return Value 


The getprotobynumber_r() function returns an integer. Possible values are: 
e -1 (unsuccessful call) 


e@ 0 (successful call) 


The struct protoent denoted by protoent_struct_addr and struct protoent_data denoted by 
protoent_data_struct_addr are both defined in <netdb.h>. The structure struct protoentis defined as: 


struct protoent [ 


char *p name; 
char *xp aliases; 
int p_proto; 
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p_name points to the character string that contains the name of the protocol. p_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the protocol. p_proto is the protocol number. 


Error Conditions 


When the getprotobynumber_r() function fails, errno can be set to: 


[EINVAL] The protoent_data structure was not properly initialized with hexadecimal zeros before 
initial use. For corrective action, see the description for structure protoent_data. 


Usage Notes 


1. The iSeries Navigator or the *& following CL commands can be used to access the protocol 
database file: 


oO WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 
Oo RMVPCLTBLE (Remove Protocol Table Entry) 


2. When the protocol information is obtained from the protocol database file, the file is opened and 
the protocol information is retrieved (if it exists) from the file. The file is then closed only if a 
setprotoent_r() call with a non-zero parameter value was not previously done. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol names returned in the protoent structure, the 
job CCSID must be something other than 65535. 


Related Information 
@ getprotobyname_r()--Get Protocol Information for Protocol Name 


@ getprotoent_r()--Get Next Entry from Protocol Database 


@ setprotoent_r(Q--Open Protocol Database 


e endprotoent_r()--Close Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getprotoent()--Get Next Entry from Protocol 
Database 


Syntax 


#include <netdb.h> 


struct protoent *getprotoent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The getprotoent() function is used to retrieve protocol information from the protocol database file. When 
getprotoent() is first called, the file is opened, and the first entry is returned. Each subsequent call to 
getprotoent() results in the next entry in the file being returned. To close the file, use endprotoent(). 


Authorities 


No authorization is required. 


Return Value 


getprotoent() returns a pointer. Possible values are: 
e NULL (unsuccessful or end-of-file) 


e p (successful), where p is a pointer to struct protoent. 


The structure struct protoent is defined in <netdb.h>. 


struct protoent { 


char *p_ name; 
char *kp aliases; 
int p_proto; 


be 


p_name points to the character string that contains the name of the protocol. p_aliases is a pointer to a 
NULL-terminated array of alternate names for the protocol. p_proto is the protocol number. 


Usage Notes 


1. 2The iSeries Navigator or the * following CL commands can be used to access the protocol 
database file: 


oO WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 


Oo RMVPCLTBLE (Remove Protocol Table Entry) 


2. The pointer returned by getprotoent() points to static storage that is overwritten on subsequent calls 
to the getprotoent(), getprotobynumber(), or getprotobyname() functions. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol names returned in the protoent structure, the 
job CCSID must be something other than 65535. 


4. Do not use the getprotoent() function in a multithreaded environment. See the multithread 
alternative getprotoent_r() function. 


5. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getprotoent() API is mapped to 
gso_getprotoent98().%& 


Related Information 


e@ %_XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e@ getprotobyname()--Get Protocol Information for Protocol Name 


@ getprotobynumber()--Get Protocol Information for Protocol Number 


e endprotoent()--Close Protocol Database 


e setprotoent()--Open Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getprotoent_r()--Get Next Entry from Protocol 
Database 


Syntax 


#include <netdb.h> 
int getprotoent_r(struct protoent 
*protoent_struct_addr, 
struct protoent_data 
*protoent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getprotoent_r() function is used to retrieve protocol information from the protocol database file. When 
the getprotoent_r() is first called, the file is opened, and the first entry is returned. Each subsequent call of 
getprotoent_r() results in the next entry in the file being returned. To close the file, use endprotoent_r(). 


Parameters 


struct protoent *protoent_address (input/output) 


Specifies the pointer to a protoent structure where the results will be placed. All results must be 
referenced through this structure. 


struct protoent_data *protoent_data_struct_addr (input/output) 


Specifies the pointer to the protoent_data structure, which is used to pass and preserve results 
between function calls. The field proto_control_blk in the protoent_data structure must be 
initialized with hexadecimal zeros before its initial use. If compatibility with other platforms is 
required, then the entire protoent_data structure must be initialized with hexadecimal zeros before 
initial use. 


Authorities 


No authorization is required. 


Return Value 


The getprotoent_r() function returns an integer. Possible values are: 


e -! (unsuccessful call) 


e 0 (successful call) 


The struct protoent denoted by protoent_struct_addr and struct protoent_data denoted by 
protoent_data_struct_addr are both defined in <netdb.h>. The structure struct protoentis defined as: 


struct protoent [ 


char *p_ name; 
char *xp aliases; 
int p_proto; 


l; 
p_name points to the character string that contains the name of the protocol. p_aliases is a pointer to a 


NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the protocol. p_proto is the protocol number. 


Error Conditions 


When the getprotoent_r() function fails, errno can be set to: 


[EINVAL] The protoent_data structure was not properly initialized with hexadecimal zeros before 
initial use. For corrective action, see the description for structure protoent_data. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the protocol 
database file: 


oO WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 
Oo RMVPCLTBLE (Remove Protocol Table Entry) 


2. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol names returned in the protoent structure, the 
job CCSID must be something other than 65535. 


Related Information 


e@ getprotobynumber_r()--Get Protocol 


e@ getprotobyname_r()--Get Protocol Information for Protocol Name 


e setprotoent_r()--Open Protocol Database 


e endprotoent_r(--Close Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getservbyname()--Get Port Number for Service 
Name 


BSD 4.3 Syntax 


#include <netdb.h> 


struct servent *getservbyname(char *service_name, 
char *protocol_name) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netdb.h> 


struct servent *getservbyname (const char *service_name, 
const char *protocol_name) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 
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The getservbyname() function is used to retrieve information about services (the protocol being used by the 
service and the port number assigned for the service). The information is retrieved from the service 
database file. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. *& 


Parameters 
service_name 


(Input) The pointer to the character string that contains the name of the service for which 
information is to be retrieved (for example, telnet). 


protocol_name 
(Input) The pointer to the character string that contains the name of the protocol that further 
qualifies the search criteria. For example, if the service_name is telnet, and the protocol_name is 


tcp, then the call will return the telnet server that uses the TCP protocol. If this parameter is set to 
NULL, then the first telnet server is returned, regardless of the protocol used. 


Authorities 


No authorization is required. 


Return Value 


getservbyname() returns a pointer. Possible values are: 
e@ NULL (unsuccessful) 


e p (successful), where p is a pointer to struct servent. 


The structure struct servent is defined in <netdb.h>. 


struct servent { 


char *s name; 
char k*xs aliases; 
int s_port; 

char *s proto 


he 


S_name points to the character string that contains the name of the service. s_aliases is a pointer to a 
NULL-terminated array of alternate names for the service. s_port is the port number assigned to the service. 
S_proto is the protocol being used by the service. 


Usage Notes 
1. 2The iSeries Navigator or the * following CL commands can be used to access the services 
database file: 
Oo WRKSRVTBLE (Work with Service Table Entries) 


o ADDSRVTBLE (Add Service Table Entry) 


Oo RMVSRVTBLE (Remove Service Table Entry) 


2. The pointer returned by getservbyname() points to static storage that is overwritten on subsequent 
calls to the getservbyname(), getservbyname(), or getservent() functions. 


3. When the service information is obtained from the service database file, the file is opened and the 
service information is retrieved (if it exists) from the file. The file is then closed only if a 
setservent() with a nonzero parameter value was not previously done. 


4. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the service name and the protocol name, specified by the 
service_name and protocol_name parameters, respectively, and for the service names returned in 
the servent structure, the job CCSID must be something other than 65535. 


5. Do not use the getservbyname() function in a multithreaded environment. See the multithread 
alternative getservbyname_r() function. 


6. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getservbyname() API is mapped 
to gso_getservbyname98().%& 


Related Information 


e@ = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e@ getservbyport()--Get Service Name for Port Number 


e getservent()--Get Next Entry from Service Database 


e setservent()--Open Service Database 


e endservent()--Close Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getservbyname_r()--Get Port Number for 
Service Name 


Syntax 


#include <netdb.h> 
int getservbyname_r(char *service_name, 
char *protocol_name, 
struct servent 
*servent_struct_addr, 
struct servent_data 
*servent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getservbyname_r() function is used to retrieve information about services: the protocol being used by 
the service and the port number assigned for the service. The information is retrieved from the service 
database file. 


Parameters 


char *service_name (input) 


Specifies the pointer to the character string that contains the name of the service for which 
information is to be retrieved (for example, telnet). 


char *protocol_name (input) 


Specifies the pointer to the character string that contains the name of the protocol that further 
qualifies the search search criteria. For example, if the service_name is telnet, and the 
protocol_name is tcp, then the call will return the telnet server that uses the TCP protocol. If this 
parameter is set to NULL, then the first telnet server is returned, regardless of the protocol used. 


struct servent *servent_struct_addr (input/output) 


Specifies the pointer to a servent structure where the results will be placed. All results must be 
referenced through this structure. 


struct servent_data *servent_data_struct_addr (input/output) 


Specifies the pointer to the servent_data structure, which is used to pass and preserve results 
between function calls. The field serve_control_blk in the servent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire servent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The getservbyname_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e@ 0 (successful call) 


The struct servent denoted by servent_struct_addr and struct servent_datadenoted by 
servent_data_struct_addr are both defined in <netdb.h>. The structure struct serventis defined as: 


struct servent [ 


char *s name; 
char k*xs aliases; 
int s_port; 

char *s proto 


]; 


S_name points to the character string that contains the name of the service. s_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the service. s_port is the port number assigned to the service. s_proto is a pointer to a character 
string that contains the name of the protocol being used by the service. 


Error Conditions 


When the getservbyname_r() function fails, errno can be set to: 


[EINVAL] The servent_data structure was not properly initialized with hexadecimal zeros before initial 
use. For corrective action, see the description for structure servent_data. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the services 
database file: 


Oo WRKSRVTBLE (Work with Service Table Entries) 
o ADDSRVTBLE (Add Service Table Entry) 
oO RMVSRVTBLE (Remove Service Table Entry) 


2. When the service information is obtained from the service database file, the file is opened and the 
service information is retrieved (if it exists) from the file. The file is then closed only if a 
setservent_r() call with a non-zero parameter value was not previously done. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the following, the job CCSID must be something other 
than 65535: 


oO The service name and the protocol name, specified by the service_name and 


protocol_name parameters, respectively 


oO The service names returned in the servent structure 


Related Information 


@ getservbyport_rQ--Get Service Name for Port Number 


@ getservent_r()--Get Next Entry from Service Database 


e setservent_r()--Open Service Database 


e endservent_r()--Close Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getservbyport()--Get Service Name for Port 
Number 


BSD 4.3 Syntax 


#include <netdb.h> 


struct servent *getservbyport (int port_number, 
char *protocol_name) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


UNIX 98 Compatible Syntax 


#define _XOPEN_ SOURCE 520 
#include <netdb.h> 


struct servent *getservbyport (int port_number, 
const char *protocol_name) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


“4 


The getservbyport() function is used to retrieve information about a service assigned to a port number. The 
information is retrieved from the service database file. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. *& 


Parameters 


port_number 
(Input) The port number for which service information is to be retrieved. 

protocol_name 
(Input) The pointer to the character string that contains the name of the protocol that further 
qualifies the search criteria. For example, if the port_number is 10, and the protocol_name is tcp, 


then the call will return the server that uses the TCP protocol on port number 10. If this parameter 
is set to NULL, then the first server is returned, regardless of the protocol used. 


Authorities 


No authorization is required. 


Return Value 


getservbyport() returns a pointer. Possible values are: 
e@ NULL (unsuccessful) 


e p (successful), where p is a pointer to struct servent. 


The structure struct servent is defined in <netdb.h>. 


struct servent { 


char *s name; 
char k*xs aliases; 
int s_port; 

char *s proto 


}; 


S_name points to the character string that contains the name of the service. s_aliases is a pointer to a 
NULL-terminated array of alternate names for the service. s_port is the port number assigned to the service. 
S_proto is the protocol being used by the service. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the services 
database file: 


Oo WRKSRVTBLE (Work with Service Table Entries) 
o ADDSRVTBLE (Add Service Table Entry) 


Oo RMVSRVTBLE (Remove Service Table Entry) 


2. The pointer returned by getservbyport() points to static storage that is overwritten on subsequent 
calls to the getservbyport(), getservbyname(), or getservent() functions. 


3. When the service information is obtained from the service database file, the file is opened and the 
service information is retrieved (if it exists) from the file. The file is then closed only if a 
setservent() with a nonzero parameter value was not previously done. 


4. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol name specified by the protocol_name 
parameter, or for the service names returned in the servent structure, the job CCSID must be 
something other than 65535. 


5. Do not use the getservbyport() function in a multithreaded environment. See the multithread 
alternative getservbyport_r() function. 


6. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getservbyport() API is mapped 
to gso_getservbyport98().& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


@ getservbyname()--Get Port Number for Service Name 


e getservent()--Get Next Entry from Service Database 


e setservent()--Open Service Database 


e endservent()--Close Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getservbyport_r()--Get Service Name for Port 
Number 


Syntax 


#include <netdb.h> 


int getservbyport_r(int port_number, 
char *protocol_name, 
struct servent *servent_struct_addr, 
struct servent_data 
*servent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getservbyport_r() function is used to retrieve information about a service assigned to a port number. 
The information is retrieved from the service database file. 


Parameters 


int port_number (input) 


Specifies the port number for which service information is to be retrieved. 


char *protocol_name (input) 


Specifies the pointer to the character string that contains the name of the protocol that further 
qualifies the search criteria. For example, if the port_number is 10, and the protocol_name is tcp, 
then the call will return the server that uses the TCP protocol on port number 10. If this parameter 
is set to NULL, then the first server is returned, regardless of the protocol used. 


struct servent *servent_struct_addr (input/output) 


Specifies the pointer to a servent structure where the results will be placed. All results must be 
referenced through this structure. 


struct servent_data *servent_data_struct_addr (input/output) 


Specifies the pointer to the servent_data structure, which is used to pass and preserve results 
between function calls. The field serve_control_blk in the servent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required then 
the entire servent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The getservbyport_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct servent denoted by servent_struct_addr and struct servent_datadenoted by 
servent_data_struct_addr are both defined in <netdb.h>. The structure struct serventis defined as: 


struct servent [ 


char *s name; 
char k*xs aliases; 
int s_port; 

char *s proto 


]; 


S_name points to the character string that contains the name of the service. s_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the service. s_port is the port number assigned to the service. s_proto is a pointer to a character 
string that contains the name of the protocol being used by the service. 


Error Conditions 


When the getservbyport_r() function fails, errno can be set to: 


[EINVAL] The servent_data structure was not properly initialized with hexadecimal zeros before initial 
use. For corrective action see the description for structure servent_data. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the services 
database file: 


Oo WRKSRVTBLE (Work with Service Table Entries) 
o ADDSRVTBLE (Add Service Table Entry) 
oO RMVSRVTBLE (Remove Service Table Entry) 


2. When the service information is obtained from the service database file, the file is opened and the 
service information is retrieved (if it exists) from the file. The file is then closed only if a 
setservent_r() call with a non-zero parameter value was not previously done. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the protocol name specified by the protocol_name 
parameter, or for the service names returned in the servent structure, the job CCSID must be 
something other than 65535. 


Related Information 


@ getservbyname_r()--Get Port Number for Service Name 


@ getservent_r(--Get Next Entry from Service Database 


e setservent_r()--Open Service Database 


e endservent_r()--Close Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getservent()--Get Next Entry from Service 
Database 


Syntax 


#include <netdb.h> 


struct servent *getservent () 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The getservent() function is used to retrieve information about services (the protocol being used by the 
service and the port number assigned for the service). The information is retrieved from the services 
database file. When getservent() is first called, the file is opened, and the first entry is returned. Each 
subsequent call to getservent() results in the next entry in the file being returned. To close the file, use 
endservent(). 


Authorities 


No authorization is required. 


Return Value 


getservent() returns a pointer. Possible values are: 
e NULL (unsuccessful or end-of-file) 


e p (successful), where p is a pointer to struct servent. 


struct servent { 


char *s name; 
char k*xs aliases; 
int s_port; 

char *s proto 


}; 


S_name points to the character string that contains the name of the service. s_aliases is a pointer to 
a NULL-terminated array of alternate names for the service. s_port is the port number assigned to 
the service. s_proto is the protocol being used by the service. 


The structure struct servent is defined in <netdb.h>. 


Usage Notes 
1. 2The iSeries Navigator or the *& following CL commands can be used to access the services 
database file: 
Oo WRKSRVTBLE (Work with Service Table Entries) 
o ADDSRVTBLE (Add Service Table Entry) 
Oo RMVSRVTBLE (Remove Service Table Entry) 
2. The pointer returned by getservent() points to static storage that is overwritten on subsequent calls 


to the getservent(), getservbyname(), or getservbyport() functions. 


3. A coded character set identifier (CCSID) of 65535 for the job requests that no database translation 
be performed. For translation to occur for the service names returned in the servent structure, the 
job CCSID must be something other than 65535. 


4. Do not use the getservent() function in a multithreaded environment. See the multithread alternative 
getservent_r() function. 


5. #*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the getservent() API is mapped to 
gso_getservent98().& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e@ getservbyname()--Get Port Number for Service Name 


@ getservbyport()--Get Service Name for Port Number 


e@ endservent()--Close Service Database 


e setservent()--Open Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


getservent_r()--Get Next Entry from Service 
Database 


Syntax 


#include <netdb.h> 
int getservent_r(struct servent *servent_struct_addr, 
struct servent_data 
*servent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The getservent_r() function is used to retrieve information about services: the protocol being used by the 
service and the port number assigned for the service. The information is retrieved from the services 
database file. When the getservent_r() is first called, the file is opened, and the first entry is returned. Each 
subsequent call of getservent_r() results in the next entry in the file being returned. To close the file, use 
endservent_r(). 


Parameters 


struct servent *servent_struct_addr (input/output) 


Specifies the pointer to a servent structure where the results will be placed. All results must be 
referenced through this structure. 


struct servent_data *servent_data_struct_addr (input/output) 
Specifies the pointer to the servent_data structure, which is used to pass and preserve results 
between function calls. The field serve_control_blk in the servent_data structure must be initialized 


with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire servent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The getservent_r() function returns an integer. Possible values are: 


e -! (unsuccessful call) 


e 0 (successful call) 


The struct servent denoted by servent_struct_addr and struct servent_datadenoted by 
servent_data_struct_addr are both defined in <netdb.h>. The structure struct serventis defined as: 


struct servent [ 


char *s name; 
char k*xs aliases; 
int s_port; 

char *s proto 


]; 


S_name points to the character string that contains the name of the service. s_aliases is a pointer to a 
NULL-terminated list of pointers, each of which points to a character string that represents an alternative 
name for the service. s_port is the port number assigned to the service. s_proto is a pointer to a character 
string that contains the name of the protocol being used by the service. 


Error Conditions 


When the getservent_r() function fails, errno can be set to: 


[EINVAL] The servent_data structure was not properly initialized with hexadecimal zeros before 
initial use. For corrective action, see the description for structure servent_data. 


Usage Notes 


2The iSeries Navigator or the *& following CL commands can be used to access the services database file: 
e WRKSRVTBLE (Work with Service Table Entries) 
e ADDSRVTBLE (Add Service Table Entry) 
e RMVSRVTBLE (Remove Service Table Entry) 

A coded character set identifier (CCSID) of 65535 for the job requests that no database translation be 


performed. For translation to occur for the service names returned in the servent structure, the job CCSID 
must be something other than 65535. 


Related Information 


@ getservbyname_r()--Get Port Number for Service Name 


@ getservbyport_r(--Get Service Name for Port Number 


@ setservent_r()--Open Service Database 


e endservent_r()--Close Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


hstrerror()--Retrieve Resolver Error Message 


Syntax 


#include 
#include 
#include 
#include 


<sys/types.h> 
<netinet/in.h> 
<arpa/nameser.h> 
<resolv.h> 


char* hstrerror(int h_error_value); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The hstrerror() function is used to retrieve the text string that describes a resolver h_errno value. 


Parameters 


h_error_value (Input) 


The h_errno received from a resolver API. 


Return Value 


The hstrerror() API returns a pointer to the error text. 


Authorities: 


No authorization is required. 


Error Conditions 


None 


Usage Notes 


1. If the h_error_value is out of range or not found, "Unknown resolver error" will be returned. 


Related Information 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e res_hostalias()--Retrieve the host alias 


@ res_ninit()--Initialize res Structure 


e res_nclose()--Close Socket and Reset res Structure 


@ res_nmkquery()--Place Domain Query in Buffer 


e res_nmkupdate()--Construct an Update Packet 


@ res_nquery(Q--Send Domain Query 


@ res_nsearch()--Search for Domain Name 


e res_nsend()--Send Buffered Domain Query 


e@ res_nsendsigned()--Send Authenticated Domain Query 


e@ res_nupdate()--Build and Send Dynamic Updates 


@ res_xlate()--Translate DNS Packets 


Example 


See res_ninit() for an example of how hstrerror() is used. 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


htonl()--Convert Long Integer to Network Byte 
Order 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 


unsigned long htonl(unsigned long host_long) 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_ SOURCE 520 
#include <netinet/in.h> 


uint32_t htonl (uint32_t host_long) 


Threadsafe: Yes 


% 


The htonl() function is used to convert a long (4-byte) integer from the local host byte order to standard 
network byte order. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


host_long 


(Input) The 4-byte integer in local host byte order that is to be converted to standard network byte 
order. 


Authorities 


No authorization is required. 


Return Value 


htonl() returns an integer. Possible values are: 


e n (where n is the 4-byte integer in standard network byte order) 


Usage Notes 


1. On the iSeries server, the value returned to the caller is the same as the value that was passed to 
htonl(), since the local host byte order does not differ from the standard network byte order. 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e ntohlQ--Convert Long Integer to Host Byte Order 


e htonsQ--Convert Short Integer to Network Byte Order 


e ntohs()--Convert Short Integer to Host Byte Order 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


htons()--Convert Short Integer to Network Byte 
Order 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 


unsigned short htons (unsigned short host_short) 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netinet/in.h> 


uintl6_t htons(uint16_t host_short) 


Threadsafe: Yes 


4 


The htons() function is used to convert a short (2-byte) integer from the local host byte order to standard 
network byte order. 


% There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 
host_short 


(Input) The 2-byte integer in local host byte order that is to be converted to standard network byte 
order. 


Authorities 


No authorization is required. 


Return Value 


htons() returns an integer. Possible values are: 


e n (where n is the 2-byte integer in standard network byte order) 


Usage Notes 


1. On the iSeries server, the value returned to the caller will be the same as the value that was passed 
to htons(), since the local host byte order does not differ from the standard network byte order. 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e ntohs()--Convert Short Integer to Host Byte Order 


e@ htonlQ--Convert Long Integer to Network Byte Order 


e ntohlQ--Convert Long Integer to Host Byte Order 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


inet_addr()--Translate Full Address to 32-bit IP 
Address 


BSD 4.3 Syntax 


#include 
#include 
#include 
#include 


unsigned 


<sys/types.h> 
<sys/socket.h> 
<netinet/in.h> 
<arpa/inet.h> 


long inet_addr(char *address_string) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _ 


#include 


XOPEN_SOURCE 520 
<arpa/inet.h> 


in_addr_t inet_addr(const char *address_string) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


% 


The inet_addr() function is used to translate an Internet address from dotted decimal format to a 32-bit IP 


address. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


address_string 
(Input) The Internet address in dotted decimal format that is to be converted to a 32-bit IP address. 


Authorities 


No authorization is required. 


Return Value 


inet_addr() returns an integer. Possible values are: 
e -! (unsuccessful) 
e n (where n is the 32-bit IP address) 


The inet_addr() subroutine returns an error value of -1 for strings that are not valid. 


Note: An Internet address with a dot notation value of 255.255.255.255 or its equivalent in a different base 
format causes the inet_addr() subroutine to return an unsigned long value of 4294967295. This value is 
identical to the unsigned representation of the error value. Otherwise, the inet_addr() subroutine considers 
255.255.255.255 a valid Internet address. 


Error Conditions 


When inet_addr() fails, errno can be set to one of the following: 
[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
address_string parameter. 


[EINVAL] Parameter not valid. 


Usage Notes 


1. Notation of the dotted decimal address string can be in one of seven formats: 
oO Format 1 - a.b.c.d 
oO Format 2 - a.b.c. 
oO Format 3 - a.b.c 
oO Format 4 - a.b. 
o Format 5 - a.b 
O 


Format 6 - a. 


o Format 7-a 


Where a component of the dotted decimal format can be decimal (for example, 7.3), octal (for 
example, 07.3) or hexadecimal (for example, Oxb.3). 


The rules for converting a dotted decimal string are as follows: 


oO For format 1, each component is interpreted as one byte of the internet address. 


oO For format 2, each component is interpreted as one byte of the internet address, and the 
rightmost byte is set to zero. 


oO For format 3, each component is interpreted as one byte of the internet address, except for 
component c, which is interpreted as the rightmost two bytes of the internet address. 


oO For format 4, each component is interpreted as one byte of the internet address, and the 
rightmost two bytes are set to zero. 


oO For format 5, each component is interpreted as one byte of the internet address, except for 
component b, which is interpreted as the rightmost three bytes of the internet address. 


o For format 6, component a is interpreted as one byte of the internet address, and the 
rightmost three bytes are set to zero. 


o For format 7, component a is returned as the internet address. 
2. #*When you develop in C-based languages and an application is compiled with the 


_XOPEN_SOURCE macro defined to the value 520 or greater, the inet_addr() API is mapped to 
qso_inet_addr98().& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface*& 


API Introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


inet_Inaof()--Separate Local Portion of IP 
Address 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


int inet_lnaof (struct in_addr internet_address) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <arpa/inet.h> 


in_addr_t inet_lnaof (struct in_addr internet_address) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


% 


The inet_Inaof() function is used to extract the local host portion of an IP address. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro. * 


Parameters 


internet_address 
(Input) The 32-bit IP address from which the local host portion of the address is to be extracted. 


Authorities 


No authorization is required. 


Return Value 


inet_Inaof() returns an integer. Possible values are: 


e@ n (where n is the local host address) 


Usage Notes 


1. When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the inet_Inaof() API is mapped to 
qso_inet_Inaof98().*& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


@ inet_makeaddr()--Combine Network Portion and Host Portion to Make IP Address 


@ inet_netof()--Separate Network Portion of IP Address 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


inet_makeaddr()--Combine Network Portion 
and Host Portion to Make IP Address 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


struct in_addr inet_makeaddr (int network_address, 
int host_address) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <arpa/inet.h> 


struct in_addr inet_makeaddr(in_addr_t network_address, 
in_addr_t host_address) 


Service Program Name: QSOSRV2 
Default Public Authority: *USE 


Threadsafe: Yes 


= 


The inet_makeaddr() function is used to generate a 32-bit IP address from the 32-bit network IP address 
and the local address of the host. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN SOURCE macro. * 


Parameters 


network_address 
(Input) The 32-bit network IP address. 


host_address 
(Input) The local host address. 


Authorities 


No authorization is required. 


Return Value 


inet_makeadadr() returns an integer. Possible values are: 
e@ n (where n is the 32-bit IP address) 


2When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE 
macro defined to the value 520 or greater, the inet_makeaddress() API is mapped to 
qso_inet_makeaddress98().*& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


Top | UNIX-Type APIs | APIs by category 


inet_netof()--Separate Network Portion of IP 
Address 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


int inet_netof (struct in_addr internet_address) 
Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <arpa/inet.h> 


in_addr_t inet_netof (struct in_addr internet_address) 
Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


4 


The inet_netof() function is used to extract the network portion of an IP address. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro. *& 


Parameters 


internet_address 
(Input) The 32-bit IP address from which the network portion of the address is to be extracted. 


Authorities 


No authorization is required. 


Return Value 


inet_netof() returns an integer. Possible values are: 


e@ n (where n is the network IP address) 


Usage Notes 


1. When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the inet_netof() API is mapped to 
gso_inet_netof98().& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e inet_InaofQ--Separate Local Portion of IP Address 


@ inet_makeaddr()--Combine Network Portion and Host Portion to Make IP Address 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


inet_network()-- Translate Network Portion of 
Address to 32-bit IP Address 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


unsigned long inet_network (char *address_string) 
Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN_SOURCE 520 
#include <arpa/inet.h> 


in_addr_t inet_network(const char *address_string) 
Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


% 


The inet_network() function is used to translate an Internet address from dotted decimal format to a 32-bit 
network IP address, in which the host part of the IP address is set to zeros. 


# There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_ SOURCE macro. * 


Parameters 
address_string 


(Input) The Internet address in dotted decimal format that is to be converted to a 32-bit network IP 
address. 


Authorities 


No authorization is required. 


Return Value 


inet_network() returns an integer. Possible values are: 


e -! (unsuccessful) 


e@ n (where n is the 32-bit network IP address) 


Error Conditions 


When inet_network() fails, errno can be set to one of the following: 
[EFAULT] Bad address. 


The system detected an address which was not valid while attempting to access the 
address_string parameter. 


[EINVAL] — Parameter not valid. 
2When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE 


macro defined to the value 520 or greater, the inet_network() API is mapped to qso_inet_network98().& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


inet_ntoa()--Translate IP Address to Dotted 
Decimal Format 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


char *inet_ntoa(struct in_addr internet_address) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The inet_ntoa() function is used to translate an Internet address from a 32-bit IP address to dotted decimal 
format. 


Parameters 


internet_address 
(Input) The 32-bit IP address that is to be converted to dotted decimal format. 


Return Value 


inet_ntoa() returns one of the following values: 
e NULL (unsuccessful) 


e s (where s is the pointer to the Internet address in dotted decimal format) 


Usage Notes 


1. The pointer returned by inet_ntoa() points to static storage that is overridden on subsequent 
inet_ntoa() functions. 


2. Do not use the inet_ntoa() function in a multithreaded environment. See the multithread alternative 
inet_ntoa_r function. 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


inet_ntoa_r()--Translate IP Address to Dotted 
Decimal Format 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


int inet_ntoa_r(struct in_addr internet_address, 
char *output_buffer, 
int output_buffer_length) 


Service Program Name: Name QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The inet_ntoa_r() function is used to translate an Internet address from a 32-bit IP address to dotted 
decimal format. 


Parameters 


struct in_addr internet_address (input) 
The 32-bit IP address that is to be converted to dotted decimal format. 


char * output_buffer (input/output) 


The pointer to the buffer that contains the dotted decimal format. 


int output_buffer_length (input) 
The length of the output buffer (length should be at least 16). 


Return Value 


The inet_ntoa_r() function returns: 
e -1 (unsuccessful call) 


e@ 0 (successful call) 


Error Conditions 


When the inet_ntoa_r() function fails, errno can be set to: 
[EINVAL] Parameter is not valid. 


This error code indicates one of the following: 


e@ The output_buffer_length length is less than 16. 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


»inet_ntop()--Convert IPv4 and IPv6 Addresses 
Between Binary and Text Form 


Syntax 


#include <sys/socket.h> 
#include <arpa/inet.h> 


const char *inet_ntop(int af, const void *src, 
char *dst, socklen_t size); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The inet_ntop() function converts a numeric address into a text string suitable for presentation. 


Parameters 


af 


(Input) Specifies the family of the address to be converted. Currently the AF_INET and AF_INET6 
address families are supported. 


src 
(Input) The pointer to a buffer that contains the numeric form of an IPv4 address if the af parameter 
is AF_INET, or the numeric form of an IPv6 address if the af parameter is AF_INET6. 

dst 
(Output) The pointer to a a buffer into which the function stores the resulting null-terminated text 
string. 

size 


(Input) The size of the buffer pointed at by dst. The calling application must ensure that the buffer 
referred to by dst is large enough to hold the resulting text string. For IPv4 addresses, the buffer 
must be at least 16 bytes. For IPv6 addresses, the buffer must be at least 46 bytes. In order to allow 
applications to easily declare buffers of the proper size to store IPv4 and IPv6 addresses in string 
form, the following two constants are defined in <netinet/in.h>: 


#define INET_ADDRSTRLEN 16 
#define INET6_ADDRSTRLEN 46 


Authorities 


No authorization is required. 


Return Value 


inet_ntop() returns a pointer. Possible values are: 
e NULL (unsuccessful) 
e non-NULL (successful) 


If successful, inet_ntop() returns a pointer to the buffer containing the text string. 


Error Conditions 


When inet_ntop() fails, errno will be set to one of the following: 


[EAFNOSUPPORT] The address family is not supported. 


[ENOSPC] The size of the result buffer is inadequate. 
[EINVAL] Parameter is not valid. 
[EFAULT] The system detected an address which was not valid while attempting to access 


the src or dst parameter. 


Usage Notes 


1. The resulting string will be in the standard IPv4 dotted-decimal format for IPv4 or one of the 
preferred forms for IPv6. See the Usage Notes for inet_pton( for a more detailed description. 


2. A job has a coded character set identifier (CCSID). The job CCSID will be used to convert the 
characters stored at dst (to allow the hexadecimal values to be shown in lower case). 


Related Information 


@ inet_ntoa()--Translate IP Address to Dotted Decimal Format 


@ inet_pton(--Convert IPv4 and IPv6 Addresses Between Text and Binary Form 


% 


API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


»inet_pton()--Convert IPv4 and IPv6 Addresses 
Between Text and Binary Form 


Syntax 


#include <sys/socket.h> 
#include <arpa/inet.h> 


int inet_pton(int af, const char *src, void *dst); 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The inet_pton() function converts an address in its standard text presentation form into its numeric binary 
form. 


Parameters 


af 


(Input) Specifies the family of the address to be converted. Currently the AF_INET and AF_INET6 
address families are supported. 


src 


(Input) The pointer to the null-terminated character string that contains the text presentation form of 
an IPv4 address if the af parameter is AF_INET, or the text presentation form of an IPv6 address if 
the af parameter is AF_INETO. See usage notes for the supported formats. 


dst 


(Output) The pointer to a buffer into which the function stores the numeric address. The calling 
application must ensure that the buffer referred to by dst is large enough to hold the numeric 
address (4 bytes for AF_INET or 16 bytes for AF_INET6). 


Authorities 


No authorization is required. 


Return Value 


inet_pton() returns an integer. Possible values are: 


e | (successful) 
e 0 (unsuccessful--input is not a valid IPv4 dotted-decimal string or a valid IPv6 address string) 


e -1 (unsuccessful--see errno) 


If successful, the buffer pointed at by dst will be updated with the numeric address. 


Error Conditions 


When inet_pton() fails with a -1, errno will be set to: 


[EAFNOSUPPORT] The address family is not supported. 
[EINVAL] Parameter is not valid. 


[EFAULT] The system detected an address which was not valid while attempting to access 
the src or dst parameter. 


Usage Notes 


1. If the af parameter of inet_pton() is AF_INET, the src string must be in the standard IPv4 
dotted-decimal form: 


ddd.ddd.ddd.ddd 


where ddd is a one to three digit decimal number between 0 and 255 (see the inet_addr() 


definition). The inet_pton function does not accept other formats (such as the octal numbers, 
hexadecimal numbers, and fewer than four numbers that inet_addr(Q) accepts). 


2. If the af parameter of inet_pton is AF_INET6, the src string must be in one of the following 
standard IPv6 text forms: 


1. The preferred form is X:x:x:x:x:x:x:x, where the 'x's are the hexadecimal values of the 
eight 16-bit pieces of the address. Leading zeros in individual fields can be omitted, but 
there must be at least one value in every field. 


2. A string of contiguous zero fields in the preferred form can be shown as "::". The "::" can 
only appear once in an address. Unspecified addresses (0:0:0:0:0:0:0:0) may be 


"oom 


represented simply as ":: 


3. A third form that is sometimes more convenient when dealing with a mixed environment of 
IPv4 and IPv6 nodes is x:x:x:x:x:x:d.d.d.d, where the "x"s are the hexadecimal values of 


the six high-order 16-bit pieces of the address, and the "d"s are the decimal values of the 
four low-order 8-bit pieces of the address (standard IPv4 representation). 


3. A job has a coded character set identifier (CCSID). The job CCSID will be used to convert the 
characters found at src (to allow the hexadecimal values to be entered in lower case). 


Related Information 


e inet_addr(Q)--Translate Full Address to 32-bit IP Address 


@ inet_ntop(Q--Convert IPv4 and IPv6 Addresses Between Binary and Text Form 


% 


API introduced: V5R2 


Top | UNIX-Type APIs | APIs by category 


ns_addr()--Translate Network Services Address 
to 12-byte Address 


Syntax 


#include <sys/types.h> 
#include <netns/ns.h> 


struct ns_addr ns_addr(char *address_string) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The ns_addr() function is used to translate a network services address from human readable format to a 
12-byte hexadecimal address. 


Parameters 


char *address_string 


(Input) The network services address in human readable format. 


Return Value 


The ns_addr() function returns an ns_addr structure. 


Usage Notes 


Notation of the human readable address string can be in many forms. The following notation rules apply to 
all the format examples shown here. 


1. There are three fields to the address string: the network field denoted by bytes nl through n4, the 
host field denoted by bytes h1 through h6, and the port number field denoted by bytes p1 and p2. 
These three fields can be separated by a period (.), a colon (:), or a (#). Once one of these three 
separator characters is encountered, the rest of the fields (the host field and the port number field) 
may be byte separated by a period or a colon. The network field cannot use byte separators because 
it is the first field and a field separator has not been encountered. Also, you may not use the same 
character as a field separator and a byte separator. 


2. Each field may be specified as either decimal, hexadecimal, or octal. Octal is specified by a 
preceding zero (for example, 011 is decimal value 9). Hexadecimal can be specified in the 
following ways: 


o Specifying Oxnn. 

o Specifying 0Xnn. 

oO Specifying xnn. 

o Specifying Xnn. 

o Specifying an H character at the end of the field. 


o Using a byte separator (only allowed for the host field or port number) in the field that 
contains the byte. 


o Using any of the characters a,b,c,d,e,f,A,B,C,D,E,F in any byte in the field. 


The following are valid formats: 
e Format 1 - nln2n3n4:h1.h2.h3.h4.h5.h6:p1.p2 
e Format 2 - nln2n3n4.h1:h2:h3:h4:h5:h6.p1:p2 
e Format 3 - nln2n3n4#h1.h2.h3.h4.h5.h6#p1.p2 
e Format 4 - nin2n3n4#h1:h2:h3:h4:h5:h6#p1 :p2 
Although they can have byte separators, the host and port fields do not need to be byte separated. Also, not 


all bytes need be specified for a given field. If not all bytes are specified, the specified bytes are 
right-justified in the field. 


Note: If the host field is not byte separated, the number must not be larger than what can be contained in a 
4-byte integer. That is, to use nonzero values for bytes hl and h2, you must byte separate the host field. 
The following formats are also valid: 

e@ Format 5 - nin2n3n4:h1h2h3h4h5h6:p1p2 

e Format 6 - nl:h1.h2.h3.h4.h5.h6:p1p2 

e@ Format 7 - nl:hlh2h3h4h5h6:p1.p2 


Not all fields need be specified. The following formats are also valid: 
e Format 8 - nl 
e Format 9 - ni:hl 
e Format 10 - nl::p1 
e Format 11 - ::pl 
As a further example, the following are just some of the ways that a network number of 71 decimal, a host 
number of 8374930 decimal, and a port number of 9341 can be specified. 
@ 71:8374930:9341 
e 71:00.00.00.7f.ca.92:9341 
e@ 71:7f.ca.92:9341 
@ 0x47:7fca92:247d 
e@ 47H:7f.ca.92:9341 
e@ 47H.7fca92.247d 


API introduced: V3R6 


Top | UNIX-Type APIs | APIs by category 


ns_ntoa()--Translate Network Services Address 
from 12-byte Address/h2> 


Syntax 


#include <sys/types.h> 
#include <netns/ns.h> 


char *ns_ntoa 
(struct ns_addr network_services_address) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The ns_ntoa() function is used to translate a network services address from a 12-byte address to a human 
readable format. 


Parameters 


struct ns_addr network_services_address 


(Input) The 12-byte network services address that is to be converted to human readable format. 


Return Value 


The ns_ntoa() function returns: 
e NULL (unsuccessful call) 


e s (where s is the pointer to the network services address in human readable format) 


Usage Notes 


1. The network services address consists of three fields, the network field, the host field, and the port 
number field. ns_ntoa() returns these fields as a single character string with the fields separated by 
the period (.) character. The character string is always terminated with a NULL character. 


2. The fields are always returned in hexadecimal notation. ns_ntoa() inserts an H character at the end 
of each field that does not contain an a,b,c,d,e,f,A,B,C,D,E or F character, in order to make it 
obvious that the notation is in hexadecimal. 


3. Not all fields need be returned. For example, if the host field and the port number field of the 
network services address both contain hexadecimal zeros, ns_ntoa() returns a character string that 
only contains the network field. 


4. The pointer returned by ns_ntoa() points to static storage that is overridden on subsequent calls to 
ns_ntoa(). 


5. Do not use the ns_ntoa() function in a multithread environment. See the multithread alternative 


ns_ntoa_r() function. 


API introduced: V3R6 


Top | UNIX-Type APIs | APIs by category 


ns_ntoa_r() -- Translate Network Services 
Address from 12-byte Address 


Syntax 


#include <sys/types.h> 
#include <netns/ns.h> 


int ns_ntoa_r(struct ns_addr 
network_services_address, 
char *output_buffer, 
int output_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The ns_ntoa_r() function is used to translate a network services address from a 12-byte address to a human 
readable format. 


Parameters 


struct ns_addr network_services_address (input) 


Specifies the 12-byte network services address that is to be converted to human readable format. 


char * output_buffer (input/output) 


Specifies the pointer to the converted string. 


int output_buffer_length (input) 
Specifies the length of the output buffer (length should at least 35). 


Return Value 


The ns_ntoa_r() function returns: 
e -! (unsuccessful call) 


e 0 (successful call) 


Error Conditions 


When the ns_ntoa_r() function fails, errno can be set to: 
[EINVAL] Parameter is not valid. 


This error code indicates one of the following: 


e@ The output_buffer_length length is less than 35. 


Usage Notes 


1. The network services address consists of three fields, the network field, the host field, and the port 
number field. ns_ntoa_r() will return these fields as a single character string with the fields 
separated by the period (.) character. The character string is always terminated with a NULL 
character. 


2. The fields are always returned in hexadecimal notation. ns_ntoa_r() will insert an 'H' character at 
the end of each field that does not contain an a,b,c,d,e,f,A,B,C,D,E or F character, in order to make 
it obvious that the notation is in hexadecimal. 


3. Not all fields need be returned. For example, if the host field and the port number field of the 
network services address both contain hexadecimal zeros, the ns_ntoa_r() routine will return a 
character string that only contains the network field. 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


ntohl()--Convert Long Integer to Host Byte 
Order 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 


unsigned long ntohl(unsigned long network_long) 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netinet/in.h> 


uint32_t ntohl (uint32_t network_long) 


Threadsafe: Yes 


4 


The ntohl() function is used to convert a long (4-byte) integer from the standard network byte order to the 
local host byte order. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro. * 


Parameters 


network_long 


(Input) The 4-byte integer in standard network byte order that is to be converted to local host byte 
order. 


Authorities 


No authorization is required. 


Return Value 


ntohl() returns an integer. Possible values are: 


e@ n(where n is the 4-byte integer in local host byte order) 


Usage Notes 


On the iSeries server, the value returned to the caller is the same as the value that was passed to ntohl(), 
since the standard network byte order does not differ from the local host byte order. 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e@ htonlQ--Convert Long Integer to Network Byte Order 


e htonsQ--Convert Short Integer to Network Byte Order 


e ntohs()--Convert Short Integer to Host Byte Order 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


ntohs()--Convert Short Integer to Host Byte 
Order 


BSD 4.3 Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 


unsigned short ntohs(unsigned short network_short) 


Threadsafe: Yes 


UNIX 98 Compatible Syntax 


#define _XOPEN SOURCE 520 
#include <netinet/in.h> 


uint16_t ntohs(uint16_t network_short) 


Threadsafe: Yes 


4 


The ntohs() function is used to convert a short (2-byte) integer from the standard network byte order to the 
local host byte order. 


= There are two versions of the API, as shown above. The base OS/400 API uses BSD 4.3 structures and 
syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface 
specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro. * 


Parameters 


network_short 


(Input) The 2-byte integer in standard network byte order that is to be converted to local host byte 
order. 


Authorities 


No authorization is required. 


Return Value 


ntohs() returns an integer. Possible values are: 


e n(where n is the 2-byte integer in local host byte order) 


Usage Notes 


On the iSeries server, the value returned to the caller is the same as the value that was passed to ntohs(), 
since the standard network byte order does not differ from the local host byte order. 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®* 


e htonsQ--Convert Short Integer to Network Byte Order 


e@ htonlQ--Convert Long Integer to Network Byte Order 


e ntohlQ--Convert Long Integer to Host Byte Order 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


res _close()--Close Socket and Reset _res 
Structure 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


void res_close (void) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_close() function is used to reset the _res structure to the beginning defaults and close a socket that 
is opened as a result of the RES_STAYOPEN flag. 


Authorities: 


No authorization is required. 


Return Value 


None 


Usage Notes 


1. If res_send() was previously called with RES_STAYOPEN set in the options field of the _res 
structure, res_close() closes the socket that was left open. res_close() does not attempt the close if 
there was no socket left open. 


2. res_close() sets the _res structure to default values. 
oO The retrans field is set to 5. 
o The retry field is set to 4. 


oO The options field has the RES_RECURSE, RES_DEFDNAMES, and RES_DNSSRCH 
bits set. 


The nscount field is set to 1. 


O 


o All other fields in the _res structure are cleared. 


o Ina thread-enabled environment _res structure is shared among all threads within a 
process. 


Related Information 


e@ res_nclose()--Close Socket and Reset res Structure 


e res_hostalias()--Retrieve the host alias 


e@ res_init()--Initialize _res Structure 


e@ res_mkquery()--Place Domain Query in Buffer 


@ res_query()--Send Domain Query 


@ res_search()--Search for Domain Name 


e@ res_send(Q--Send Buffered Domain Query 


@ res_xlate()--Translate DNS Packets 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


res _findzonecut()--Find the Enclosing Zone 
and Servers 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_findzonecut (state* res, 
const char *domain_name, 
ns_class class, 
int options, 
char *zone_name, 
size_t zone_size, 
struct in_addr *addresses, 
int num_addresses) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_findzonecut() queries name servers until it finds the enclosing zone and its master name servers for 
the specified domain name. 


Parameters 


res 


(Input) The pointer to the state structure. 


domain_name 


(Input) The pointer to the domain name whose enclosing zone is desired. 


class 

(Input) The class of domain_name. 
options 

(Input) Processing options, may be RES_EXHAUSTIVE. 
zone_name 


(Output) The pointer to the enclosing zone name found. 


zonesize 


(Input) The size of the zone_name buffer. 


addresses 


(Output) The name server addresses found for the enclosing zone. 


num_addresses 


(Input) The maximum number of addresses to be returned. 


Authorities 


No authorization is required. 


Return Value 


res_findzonecut() returns an integer. Possible values are: 


e@ <0- (unsuccessful). 
e =0 - zone_name is now valid, but addresses wasn't changed. 


e@ > 0 - zone_name is now valid, and the return value is number of addresses found. 


Error Conditions 


When the res_findzonecut() function fails, res_findzonecut() can set errno to one of the following: 


[ECONVERT] Either the input packet could not be translated to ASCII or the answer received 
could not be translated to the coded character set identifier (CCSID) currently in 
effect for the job. 


[EDESTADDRREQ] No zone could be found for the domain. 


[EFAULT] The system detected a pointer that was invalid while attempting to access an 
input pointer. 


[EINVAL] One of the following reasons: 
e An invalid length or NULL pointer was passed to res_findzonecut() or 
e The res appears to be initialized but the reserved field is not set to zeros. 


Note: No attempt is made to initialize the res structure if it was initialized 
previous to the res_findzonecut() being issued. 


[EMSGSIZE] An invalid message length was returned on an answer. 


[EPROTOTYPE] The answer to a query had the wrong domain name. 


Note: There are numerous other values that errno can be set to by the resolver and sockets functions that 
res_findzonecut() calls. Refer to other functions for the other values. 


Usage Notes 


1. res_findzonecut() calls res_mkquery() and res_send() to query the specified server for the zone 
information. 


2. res_findzonecut() calls res_ninit() if the res structure has not been initialized. 


3. res_findzonecut() assumes that the data passed to it is EBCDIC and is in the default coded character 
set identifier (CCSID) currently in effect for the job. It translates the data from the default CCSID 
currently in effect for the job to ASCII (CCSID 819) before the data is sent out to a name server. 
The response that it receives from the name server is returned in the default CCSID currently in 
effect for the job. 


Related Information 


e res_nclose()--Close Socket and Reset res Structure 


e res_hostalias()--Retrieve the host alias 


@ res_ninit()--Initialize res Structure 


e@ res_nmkquery()--Place Domain Query in Buffer 


e@ res_nmkupdate()--Construct an Update Packet 


@ res_nquery()--Send Domain Query 


@ res_nsearch()--Search for Domain Name 


e@ res_nsend()--Send Buffered Domain Query 


e res_nsendsignedQ--Send Authenticated Domain Query 


@ res_nupdate()--Build and Send Dynamic Updates 


e res_xlate()--Translate DNS Packets 


API introduced: V5R1 
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res_hostalias()--Retrieve the host alias 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


const char * res_hostalias(const state* res, 
const char* name, 
char* destination, 
size_t destination_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_hostalias() looks up the specified name in the host aliases file specified by the environment 
variable HOSTALIASES. 


A user may create a host aliases file. This file maps user defined aliases to host names, unlike the OS/400 
host table (or a DNS) which maps host names to ip addresses. Also, it requires no special authorities for a 
user to define an alias. It's simply a shorthand for a server which can be easily changed and controlled by 
users. No iSeries server default alias file is created. 


The format is simply an alias followed by blank(s) followed by a domain name. For example, mypc may be 
an alias for m999.mydomain.ibm.com and myaix may be an alias for m111.mydomain.ibm.com: 


mypc m999.mydomain.ibm.com. 
myaix m111.mydomain.ibm.com 


Other functions, like res_nsearch() or gethostbyname_r() will resolve an alias like "mypc" to the full 
domain name "m999.mydomain.ibm.com." before querying the DNS or OS/400 host table. 


Note:An alias may not contain periods. 


Parameters 


res 


(Input) The pointer to the state structure. 


name 


(Input) The pointer to the host name. 


destination 
(Output) The pointer to the destination buffer. This pointer will be the return value if the call 
succeeds. 


destination_length 
(Input) The length of the destination buffer. 


Authorities 


Authorization of *R (allow access to the object) to the host aliases file specified by the HOSTALIASES 
environment variable. 


You also need *X authority to each directory in the path of the host aliases file. 


Return Value 


(NULL) No alias found or an error occurred. 


(destination) A pointer to the destination buffer updated with the alias found. 


Error Conditions 


When the res_hostalias() function fails, errno can be set to one of the following: 


[EACCES] Permission denied. The process does not have the appropriate privileges to the host aliases 
file specified by the HOSTALIASES environment variable. 


[EFAULT] The system detected a pointer that was invalid while attempting to access an input pointer. 


[EINVAL] One of the following reasons: 


e The res appears to have been previously initialized but the reserved field is not set 
to zeros or an input pointer was NULL. 


e An alias was found that contains a period. 


Usage Notes 
1. If the RES_NOALIASES option is set, no processing is done and a NULL will be returned. 


2. If the res structure has not been initialized, res_ninit() will be called. 


Related Information 


e res_findzonecut()--Find the Enclosing Zone and Servers 


@ res_init()--Initialize res Structure 


e res_nclose()--Close Socket and Reset res Structure 


@ res_nmkquery()--Place Domain Query in Buffer 


@ res_nquery()--Send Domain Query 


@ res_nsearch()--Search for Domain Name 


e@ res _nsend()--Send Buffered Domain Quer 


e res_xlate()--Translate DNS Packets 


API introduced: V5R1 
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res_init()--Initialize res Structure 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


void res_init (void) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_init() function is used to initialize the _res structure for name resolution. Two bits are set in the 
structure to indicate that it has been initialized. (These are the RES_INIT and RES_XINIT bits in the 
options field of the _res structure.) Also, the default domain name and other components of the domain to 
search are put into the _res structure. 


The _res structure is defined in <resolv.h>. 


struct state { 


int retrans; 
int retry; 

long options; 
int nscount; 


struct sockaddr_in nsaddr_list [MAXNS]; 
u_short id; 

char defdname [MAXDNAME ] ; 

char reserved0 [1]; 

char reservedl1 [13]; 

char *dnsrch [MAXDNSRCH+1]; 


/* Extended state structure begins here.*/ 


struct { 
struct in_addr addr; 
uint mask; 
} sort_list [MAXRESOLVSORT]; 
int res_h_errno; 
int extended_error; 


unsigned ndots:4; 
unsigned nsort:4; 

char state_data[27]; 
int internal_use[4]; 
char reserved[444]; 


#define nsaddr nsaddr_list[0] 


extern struct state _res; 
retrans 


Time interval in seconds between retries. The default is received from QUSRS YS/QATOCTCPIP 
which is configured with the Change TCP/IP Domain (CHGTCPDMN) command 


retry 


Number of times to retransmit. The default is received from QUSRSYS/QATOCTCPIP which is 
configured with the Change TCP/IP Domain (CHGTCPDMN) command 


options 


Contains flag bits to indicate the different resolver options. The default is RES_DEFAULT 


nscount 


Number of name servers. res_ninit() sets the number of name servers to the number found in the 
database file. The maximum is 3 


nsaddr_list 


Contains the address(es) of the name server(s) 


id 
Current packet ID. The id is initialized to a random number 

defdname 
Default domain name or the search list 

dnsrch 
Contains the components of the search list. By default it points to components of defdname which 
contains the local domain or the configured search list. However a program may allocate separate 
storage for a customized search list and set the elements of dnsrch to point to it. Each component 
pointed to by an element of dnsrch must be NULL terminated. 

sort_list 


List of address/mask pairs that will be used to sort the results of a gethostbyname() or 
gethostbyname_r() operation 


res_h_errno 


Holds the last h_errno or errno set by the resolver for this context 


ndots 


Number of dots in a name that will trigger an absolute query instead of using the dnsrch 


nsort 


Number of elements in the sort_list array 


state_data 


Used internally by the resolver 


reserved0,reservedl and reserved 


Fields are that set to zeros by res_ninit() or res_init(). If the res structure is manually initialized by 
a program, it also must set these structures to zeros. 


nsaddr 


Defined for backward compatibility 


options 


The value for the options is constructed by performing an OR operation on the following values: 


RES_INIT Indicates that the res structure has been initialized. 

RES_AAONLY Requests the answer be authoritative and not from a name server's 
cache. 

RES_USEVC Tells the resolver to use TCP instead of UDP. 

RES_IGNTC Tells the resolver to ignore truncation. 

RES_RECURSE Specifies that recursion is desired. 

RES_DEFNAMES Appends the default domain name to single label queries. 

RES_STAYOPEN Causes the TCP connection to remain open (used with RES_USEVC). 

RES_DNSRCH Searches using dnsrch. 

RES_INSECURE1 Disables type 1 security. Type 1 security rejects responses that didn't 


come from one of the configured DNS servers. 


RES_INSECURE2 Disables type 2 security. Type 2 security checks the question section 
of the reply to ensure it matches the original query sent. 


RES_NOALIASES Tells the resolver to ignore the HOSTALIASES environment 
variable. 
RES_ROTATE Tells the resolver to rotate through the list of DNS servers 


(nsadar_list). 


RES_NOCHECKNAME | Tells the resolver not to check host names in replies for disallowed 
characters such as underscore (_), non-ASCH, or control characters. 


RES_KEEPTSIG Stops the resolver from stripping TSIG records on replies. 


RES_NOCACHE Do not look in the resolver answer cache. Query the name server. The 
answer may still be locally cached. 


The following four values are OS/400 specific. 


RES_XINIT Indicates that the extended portion of the res structure has been 
initialized. 
RES_CP850 Use ASCII code page 850 and not ASCII code page 819. 


RES_RETRYTCP Retry with a TCP connection if the UDP connection fails for any reason. 


RES_NSADDRONLY Only use the list of addresses in nsaddr. There may be a separate 
SOCKS DNS configured that would normally be used. 


RES_DEFAULT This is the default. Causes an OR operation on the RES_RECURSE, 
RES_DEFNAMES, RES_DNSRCH values. 


Authorities: 


No authorization is required. 


Return Value 


None. 


Error Conditions 


res_init() can set errno to the following: 


[EINVAL] _res appears to have been previously initialized but the reserved field is not set to 
ZeTOS. 


[EUNKNOWN]_ res_init() was unable to retrieve the DNS server configuration. 


Usage Notes 


1. If no entry was configured with Change TCP/IP Domain (CHGTCPDMN), then res_init() does the 


following: 


oO Calls gethostname() to get the default domain name. The default domain name in this case 
is the host name minus the first component of the name. For example, if the host name is 
ABC.RCHLAND.IBM.COM, the default name is RCHLAND.IBM.COM. 


Oo Calls getservbyname() to get the port number. 


o Uses hard-coded defaults for retrans, retry and ndots (5, 4 and 1 respectively). 


2. The default initialization values can be overridden with enviroment variables. Note:The name of 
the environment variable must be uppercased. The string value may be mixed case. Japanese 
systems using CCSID 290 should use uppercase characters and numbers only in both environment 
variables names and values. 


o LOCALDOMAIN 


The configured search list (struct state.defdname and struct state.dnsrch) can be overridden 
by setting the environment variable LOCALDOMAIN to a space-separated list of up to 6 
search domains with a total of 256 characters (including spaces). If a search list is 
specified, the default local domain is not used on queries. 


Oo RES_OPTIONS allows certain internal resolver variables to be modified. The environment 
variable can be set to one or more of the following space-separated options: 


NDOTS:n sets a threshold for the number of dots which must appear in a name 
given to res_query() before an initial absolute query will be made. The default for 
nis ~~1", meaning that if there are any dots in a name, the name will be tried first as 
an absolute name before any search list elements are appended to it. 


TIMEOUT:n sets the amount of time (in seconds) the resolver will wait for a 
response from a remote name server before giving up and retrying the query. 


ATTEMPTS:n sets the number of queries the resolver will send to a given 
nameserver before giving up and trying the next listed nameserver. 


ROTATE sets RES_ROTATE in _res.options , which causes round robin selection 
of nameservers from among those listed. This has the effect of spreading the query 
load among all listed servers, rather than having all clients try the first listed server 
first every time. 


NO-CHECK-NAMES sets RES_NOCHECKNAME in _res.options , which 
disables the modern BIND checking of incoming host names and mail names for 
invalid characters such as underscore (_), non-ASCII, or control characters. 


Oo QIBM_BIND_RESOLVER_FLAGS 


The RES_DEFAULT options (struct state.options) and system configured values (Change 
TCP/IP Domain - CHGTCPDMN) can be overridden by setting the environment variable 
QIBM_BIND_RESOLVER_FLAGS to a space separated list of resolver option flags. The 
state.options structure will be initialized normally, using RES_DEFAULT, OPTIONS 
environment values and CHGTCPDMN configured values. Then this environment varible 
will be used to override those defaults. The flags named in this environment variable may 
be prepended with a '+', '-' or 'NOT_' to set (‘+’) or reset (‘-',, NOT_') the value. For example, 


to turn on RES-. NOCHECKNAME and turn off RES ROTATE: 
ADDENVVAR ENVVAR(QIBM_BIND_RESOLVER_FLAGS) 
VALUE('RES_NOCHECKNAME NOT_RES_ROTATE'’) 

or 

ADDENVVAR ENVVAR(QIBM_BIND_RESOLVER_FLAGS) 
VALUE('+RES_-NOCHECKNAME -RES_ ROTATE’) 


o QIBM_BIND_RESOLVER_SORTLIST 


A sort list (struct state.sort_list) can be configured by setting the environment variable 
QIBM_BIND_RESOLVER_SORTLIST to a space-separated list of up to 10 ip 
addresses/mask pairs in dotted decimal format (9.5.9.0/255.255.255.0) 


Note: Environment variables are only checked after a successful call to res_init() or res_ninit(). So 
if the structure has been manually initialized, environment variables are ignored. Also note that the 
structure is only initialized once so later changes to the environment variables will be ignored. 


3. res_init() is called by res_send(), res_mkquery(), res_search(), and res_query() if they detect the 
_res structure has not been initialized (RES_INIT option). res_init() can also be called directly to 
change the defaults and hence, change the behavior of one of the above routines. For example, if 
you want to use TCP rather than attempt UDP first, simply call res_init() directly. Then before the 
call to res_send(), set the RES_USEVC bit in the options flag. Other things in the _res structure, 
like the number of retries or time interval between retries, can be changed in a like manner. 


4. If the server protocol configured with Change TCP/IP Domain (CHGTCPDMN) is set to TCP, then 
res_init() sets the RES_USEVC bit in the options field of the _res structure. 


5. In a thread-enabled environment the _res structure is shared among all threads within a process. 


Related Information 


e hstrerror()--Retrieve Resolver Error Message 


@ res_ninit()--Initialize res Structure 


e res_hostalias()--Retrieve the host alias 


e res_close()--Close Socket and Reset _res Structure 


e res_mkquery()--Place Domain Query in Buffer 


@ res_query()--Send Domain Query 


@ res_search()--Search for Domain Name 


e res_send(--Send Buffered Domain Query 


e res_xlate()--Translate DNS Packets 
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res_mkquery()--Place Domain Query in Buffer 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_mkquery(int operation, 
char *domain_name, 
int class, 
int type, 
char *search_data, 
int search_data_length, 
struct rrec *reserved, 
char *query_buffer, 
int query_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_mkquery() function is used to make standard query messages (DNS packets) for name servers. 


Parameters 


operation 


(Input) The query operation desired. This gets put into OPCODE in the header of the packet. 
Common values are listed below (see <arpa/nameser.h> for all possible values): 


ns_o_query or QUERY Standard query request. (This value is almost always used.) 


domain_name 


(Input) The pointer to the name of the domain. 


class 


(Input) The class of data being looked for. Common values are listed below (see <arpa/nameser.h> 
for all possible values): 


ns_c_inor C_IN Specifies the ARPA Internet. 


ns_c_any or C_ANY This is the wildcard match. 


type 
(Input) The type of request being made. Common values are listed below (see <arpa/nameser.h> 
for all possible values): 


ns_t_aorT A Host address. 
2ns_t_aaaa IPv6 address.*& 
ns_t_ns or T_NS Authoritative server. 


ns_t_cname or T CNAME _ Canonical name. 


ns_t_soaor T_ SOA Start of authority zone. 
ns_t_wks or T WKS Well-known service. 
ns_t_ptr or T_PTR Domain name pointer. 


ns_t_hinfo or T_HINFO Host information. 


ns_t_mx or T_ MX Mail routing information. 
ns_t_txt or T_TXT Text strings. 
ns_t_any or T_ANY Wildcard match. 


search_data 
(Input) A buffer containing the data for inverse queries. It is NULL for types other than IQUERY. 


search_data_length 
(Input) The length of search_data. It is NULL for types other than IQUERY. 


reserved 
(Input) A reserved and currently unused parameter. It is always a NULL pointer (defined for 


compatibility). 


query_buffer 


(Output) A pointer to a user-supplied location containing the query message. 


query_buffer_length 
(Input) The length of query_buffer. 


Authorities: 


No authorization is required. 


Return Value 


res_mkquery() returns an integer. Possible values are: 


e -1 (unsuccessful) 


e n (successful), where n is the size of the query. 


Error Conditions 


When the res_mkquery() function fails, errno can be set to one of the following: 


[EFAULT] The system detected a pointer that was invalid while attempting to access an input 
pointer. 


[EINVAL] The _res appears to be initialized but the reserved field is not set to zeros. 


[EMSGSIZE] The message buffer was too small. The query was larger than the value of 
query_buffer_length 


Usage Notes 


1. res_mkquery() creates a standard query message (DNS packet). It fills in the header fields, 
compresses the domain name into the question section, and fills in the other question fields. This 
query message is placed in query_buffer. 


2. res_mkquery() calls res_init() if the _res structure has not been initialized. 
3. res_mkquery() expects EBCDIC data as input. The output from res_mkquery() is also EBCDIC. 


4. In a thread-enabled environment, the _res structure is shared among all threads within a process. 


Related Information 


e@ res_nmkquery()--Place Domain Query in Buffer 


e res_hostalias()--Retrieve the host alias 


@ res_init()--Initialize _res Structure 


e@ res_close()--Close Socket and Reset _res Structure 


@ res_query()--Send Domain Query 


@ res_search()--Search for Domain Name 


e@ res_send()--Send Buffered Domain Query 


@ res_xlate()--Translate DNS Packets 
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res_nclose()--Close Socket and Reset res 
Structure 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


void res_nclose(state* res) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nclose() function is similar to res_close() but it uses a user-declared res pointer instead of the 
shared _res. 


For a description of this function and more information on the parameters, authorities required, return 
values, error conditions, error messages, usage notes, and related information, see res_close()--Close Socket 


and Reset _res Structure. 


Parameters 


res 
(Input) The pointer to the state structure. 


Related Information 


e res_close()--Close Socket and Reset _res Structure 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e@ res_hostalias()--Retrieve the host alias 


® res_ninit()--Initialize res Structure 


e res_nmkquery()--Place Domain Query in Buffer 


@ res_nquery()--Send Domain Query 


e@ res_nsearch()--Search for Domain Name 


e@ res_nsend()--Send Buffered Domain Query 


e res_xlate()--Translate DNS Packets 
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res_ninit()--Initialize res Structure 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_ninit(state* res) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_ninit() function is similar to res_init() but it uses a user-declared res pointer instead of the shared _res. 


For a description of this function and more information on the parameters, authorities required, return values, 
error conditions, error messages, usage notes, and related information, see res_init()--Initialize _res Structure. 


Parameters 
res 
(Input/Output) The pointer to the state structure. 


The RES_INIT and RES_XINIT options flags must be initialized to zero before the first call to any resolver API 
or the res structure will not be properly initialized. For example: 


state res; 
res.options &= ~ (RES_INIT | RES_XINIT); 
int n = res_ninit(&res); 


Return Value 


res_ninit() returns an integer. Possible values are: 
e -1 (unsuccessful) 


e@ 0 (successful) 


Error Conditions 


When the res_ninit() function fails, errno can be set to one of the following: 
[EFAULT] The system detected a pointer that was invalid while attempting to access an input pointer. 


[EINVAL] The res appears to have been previously initialized but the reserved field is not set to zeros. 


Related Information 


e hstrerror()--Retrieve Resolver Error Message 


e res_init()--Initialize res Structure 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e@ res_hostalias()--Retrieve the host alias 


e@ res_nclose()--Close Socket and Reset res Structure 


e@ res_nmkquery()--Place Domain Query in Buffer 


@ res_nquery()--Send Domain Query 


e@ res_nsearch()--Search for Domain Name 


e res_nsend()--Send Buffered Domain Query 


e res_xlate()--Translate DNS Packets 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example shows how res_ninit() is used and how initialization defaults can be changed after 
initialization: 


#include <stdio.h> 
#include <errno.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 
#include <netdb.h> 


/* Declare update records - a zone record, a pre-requisite record, and 
an update record */ 
ns_updrec update_records[] = 
{ 
{ 

{NULL, NULL}, 
{NULL, &update_records[1]}, 
ns_s_ zn, /* a zone record */ 
"mydomain.ibm.com.", 
ns_c_in, 
ns_t_soa, 


NULL, 
0, 

0, 
NULL, 
NULL, 
0 


{NULL, NULL}, 
{&update_records [0], &update_records[2]}, 


ns_s_pr, /* pre-req record */ 
"mypc.mydomain.ibm.com.", 

ns_c_in, 

ns_t_a, 

0, 

NULL, 

0, 

ns_r_nxdomain, /* record must not exist */ 
NULL; 

NULL, 

0 


{NULL, NULL}, 

{&update_records[1],NULL}, 

ns_s_ud, /* update record */ 
"mypc.mydomain.ibm.com.", 

ns_c_in, 

ns_t_a, 

10, 

(unsigned char *)"10.10.10.10", 

ni Bele 

ns_uop_add, /* to be added */ 
NULL, 

NULL, 

0 


he 


void main() 
{ 
struct state res; 
int result; 
unsigned char update_buffer[2048]; 
int buffer_length = sizeof update_buffer; 


unsigned char answer_buffer[2048]; 

/* Turn off the init flags so that the structure will be initialized 
a 

res.options &= ~ (RES_INIT | RES_XINIT); 


result = res_ninit (&res); 


/* Put processing here to check the result and handle errors 


wep 


/* We choose to use TCP and not UDP, so set the appropriate option now 


that the res variable has been initialized. 
ae 
res.options |= RES_USEVC; 


/* Send a query for mypc.mydomain.ibm.com address records 
‘aire 
result = res_nquerydomain(&res,"mypc", "mydomain.ibm.com.", ns_c_in, 
ns_t_a, 
update_buffer, buffer_length); 


/* Sample error handling and printing errors 


*/ 
if (result == -1) 
{ 
printf("\nquery domain failed. result = %d \nerrno: %$d: %s \nh_errno: 
$d: %s", 
result, 


errno, strerror(errno), 
h_errno, hstrerror(h_errno)); 
return; 


/* The output on a failure will be: 


query domain failed. result = -1 
errno: O: There is no error. 
h_errno: 5: Unknown host 


*/ 


/* Build an update buffer (packet to be sent) from the update records 

*/ 

result = res_nmkupdate(&res, update_records, update_buffer, 
buffer_length) ; 


/* Put processing here to check the result and handle errors 
*/ 
} 


{ 

char zone_name[NS_MAXDNAME] ; 

size_t zone_name_size = sizeof zone_name; 
struct sockaddr_in s_address; 

struct in_addr addresses[1]; 

int number_addresses = 1; 


/* Find the DNS server that is authoritative for the domain 
that we want to update 
ae 


result = res_findzonecut (&res, "mypc.mydomain.ibm.com", ns_c_in, 0, 
zone_name, zone_name_size, 
addresses, number_addresses); 


/* Put processing here to check the result and handle errors 


sai 


/* Check if the DNS server found is one of our regular 


DNS addresses 


sas 

s_address.sin_addr = addresses[0]; 
s_address.sin_family = res.nsaddr_list[0].sin_family; 
s_address.sin_port = res.nsaddr_list[0].sin_port; 


memset (s_address.sin_zero, 0x00, 8); 

result = res_nisourserver(&res, &S_address); 

/* Put processing here to check the result and handle errors 
sav 


/* Set the DNS address found with res_findzonecut into the res 
structure. We will send the (TSIG signed) update to that DNS. 
sv 


res.nscount = 1; 
res.nsaddr_list[0] = s_address; 


} 


{ 
ns_tsig_key my_key = { 


"my-long-key", /* This key must exist on the DNS */ 
NS_TSTG_ALG _HMAC_MD5, 

(unsigned char*) "“abcdefghijklmnopqrstuvwx", 

24 


}; 


/* Send a TSIG signed update to the DNS 
sy 
result = res_nsendsigned(&res, update_buffer, result, 
émy_key, 
answer_buffer, sizeof answer_buffer); 


/* Put processing here to check the result and handle errors 


aie 


/* The res_findzonecut(), res_nmkupdate(), and res_nsendsigned() could 
be replaced with one call to res_nupdate() using update_records [1] 
to skip the zone record:: 


result = res_nupdate(&res, &update_records[1], &my_key); 


ai 


return; 
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res_nisourserver()--Check Server Address 


#include 
#include 
#include 
#include 


<sys/types.h> 
<netinet/in.h> 
<arpa/nameser.h> 
<resolv.h> 


int res_nisourserver(state* res, 


const struct sockaddr_in server) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nisourserver() looks up the specified server address in the ns_addr_list[] of the specified res 


structure. 


Parameters 


res 


(Input) The pointer to the state structure. 


server 


(Input) The server address to check. 


Authorities: 


No authorization is required. 


Return Value 


(0) Server not found in ns_addr_list[]. 


(>0) Server found in ns_addr_list[]. 


(<0) Error. 


Error Conditions 


When the res_nisourserver() function returns an error, errno will be set to one of the following: 
[EFAULT] The system detected a pointer that was invalid while attempting to access an input pointer. 


[EINVAL] One of the following reasons: 
e A NULL pointer was passed to res_nisourserver() or 


e The res appears to be initialized but the reserved field is not set to zeros. 


Related Information 


e res_findzonecut()--Find the Enclosing Zone and Servers 


@ res_init()--Initialize res Structure 


@ res_nclose()--Close Socket and Reset res Structure 


e@ res_nmkquery()--Place Domain Query in Buffer 


@ res_nquery()--Send Domain Query 


@ res_nsearch()--Search for Domain Name 


e res_nsend()--Send Buffered Domain Quer 


@ res_xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res_nmkquery()--Place Domain Query in 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_nmkquery(state* res, 
int operation, 
const char *domain_name, 
int class, 
int type, 


const unsigned char *search_data, 


int search_data_length, 


const unsigned char *reserved, 
unsigned char *query_buffer, 


int query_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


Buffer 


The res_nmkquery() function is similar to res_mkquery() but it uses a user-declared res pointer instead of 


the shared _res. 


For a description of this function and more information on the parameters, authorities required, return 
values, error conditions, error messages, usage notes, and related information, see res_mkquery()--Place 


Domain Query in Buffer. 


Parameters 


res 


(Input/Output) The pointer to the state structure. 


Related Information 


e@ res_mkquery()--Place Domain Query in Buffer 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e res_hostalias()--Retrieve the host alias 


@ res_ninit()--Initialize res Structure 


e res_nclose()--Close Socket and Reset res Structure 


@ res_nquery()--Send Domain Query 


@ res_nsearch()--Search for Domain Name 


e@ res_nsend()--Send Buffered Domain Query 


e@ res_xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res_nmkupdate()--Construct an Update Packet 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_nmkupdate(state* res, 
ns_updrec *update_record, 
unsigned char *buffer, 
int buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nmkupdate() function builds a dynamic update packet from the linked list of update records. 


Parameters 


res 


(Input) The pointer to the state structure. 


update_record 
(Input) The pointer to the linked list of update records. See res_nupdate() for more information. 


buffer 
(Input) The pointer to the buffer to be filled in with the update packet. 


buffer_length 
(Input) The length of the buffer. 


Authorities 


No authorization is required. 


Return Value 


res_nmkupdate() returns an integer. Possible values are: 


e n (successful), where n is the actual size of the resulting update packet. 


e -1 (unsuccessful) An error occurred parsing a word or number in the rdata portion of the update 
records. 


e -2 (unsuccessful) The buffer was too small 


e -3 (unsuccessful) The zone section is not the first section in the linked list, or the section order has a 
problem. The section order is ns_s_zn, ns_s_pr and ns_s_ud. 


e -4 (unsuccessful) A number overflow occurred. 


e@ -5 (unsuccessful) Unknown operation or no records found. 


Error Conditions 


When the res_nmkupdate() function fails, res_nmkupdate() can set errno to one of the following: 


[ECONVERT] Either the input packet could not be translated to ASCII or the answer received could 
not be translated to the coded character set identifier (CCSID) currently in effect for the 


job. 

[EFAULT] The system detected a pointer that was invalid while attempting to access an input 
pointer. 

[EINVAL] One of the following reasons: 


e An invalid length or NULL pointer was passed to res_nmkupdate() or 


e The res appears to be initialized but the reserved field is not set to zeros. 


Note: No attempt is made to initialize the res structure if it was initialized previous to 
the res_nmkupdate() being issued. 


[EMSGSIZE] The message buffer was too small. The return value was -2. 


Usage Notes 


1. res_nmkupdate() calls res_ninit() if the res structure has not been initialized. 


2. res_nmkupdate() assumes that the data passed to it is EBCDIC and is in the default coded character 
set identifier (CCSID) currently in effect for the job. It translates the data from the default CCSID 
currently in effect for the job to ASCII (CCSID 819) before the data is sent out to a name server. 
The response that it receives from the name server is returned in the default CCSID currently in 
effect for the job. 


Related Information 


e@ res_nclose()--Close Socket and Reset res Structure 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e res_hostalias()--Retrieve the host alias 


@ res_ninit()--Initialize res Structure 


e@ res_nmkquery()--Place Domain Query in Buffer 


@ res_nquery()--Send Domain Query 


e@ res_nsearch()--Search for Domain Name 


@ res_nsend()--Send Buffered Domain Query 


e@ res_nsendsignedQ--Send Authenticated Domain Query 


@ res_nupdate()--Build and Send Dynamic Updates 


e@ res_xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res nquery()--Send Domain Query 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_nquery(state* res, 
const char *domain_name, 
int class, 
int type, 
unsigned char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nquery() function is similar to res_query() but it uses a user-declared res pointer instead of the 
shared _res. 


For a description of this function and more information on the parameters, authorities required, return 
values, error conditions, error messages, usage notes, and related information, see res_query()--Send 


Domain Query. 


Parameters 


res 


(Input/Output) The pointer to the state structure. 


Related Information 


@ res_query()--Send Domain Query 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e res_hostalias()--Retrieve the host alias 


® res_ninit()--Initialize res Structure 


nmkquery()--Place Domain Query in Buffer 


@ res 


nclose()--Close Socket and Reset res Structure 


nsearch()--Search for Domain Name 


nsend()--Send Buffered Domain Query 


xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res nquerydomain()--Send 2 String Domain 
Query 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


void res_nquerydomain(state* res, 
const char *stringl, 
const char *string2, 
int class, 
int type, 
unsigned char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nquerydomain() concatenates string/ + string2 into anew domain_name parameter and calls 
res_nquery(). For more information on domain_name, the remaining parameters, authorities required, 


return values, and related information, see res_nquery()--Send Domain Query. 


Parameters 


string] 


(Input) The pointer to the first string. In practice this is generally a host name. 


string2 


(Input) The pointer to the first string. In practice this is generally a zone name. 


Related Information 


@ res_nquery()--Send Domain Query 


Example 


See res_ninit() for an example of how hstrerror() is used. 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res_nsearch()--Search for Domain Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_nsearch(state* res, 
const char *domain_name, 
int class, 
int type, 
unsigned char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nsearch() function is similar to res_search() but it uses a user-declared res pointer instead of the 
shared _res. 


For a description of this function and more information on the parameters, authorities required, return 
values, error conditions, error messages, usage notes, and related information, see res_search()--Search for 


Domain Name. 


Parameters 


res 
(Input/Output) The pointer to the state structure. 


Related Information 


@ res_search()--Search for Domain Name 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e res_hostalias()--Retrieve the host alias 


@ res_ninit()--Initialize res Structure 


@ res_nmkquery()--Place Domain Query in Buffer 


@ res_nquery()--Send Domain Query 


@ res_nclose()--Close Socket and Reset res Structure 


e@ res_nsend()--Send Buffered Domain Quer 


e res_xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res _nsend()--Send Buffered Domain Query or 
Update 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_nsend(state* res, 
const unsigned char *query_buffer, 
int query_buffer_length, 
unsigned char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nsend() function is similar to res_send() but it uses a user-declared res pointer instead of the 
shared _res. 


For a description of this function and more information on the parameters, authorities required, return 
values, error conditions, error messages, usage notes, and related information, see res_send()--Send 


Buffered Domain Query. 


Parameters 


res 


(Input/Output) The pointer to the state structure. 


Related Information 


e res_send()--Send Buffered Domain Query 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e@ res_hostalias()--Retrieve the host alias 


® res_ninit()--Initialize res Structure 


e@ res_nmkquery()--Place Domain Query in Buffer 


@ res_nquery()--Send Domain Query 


e@ res_nsearch()--Search for Domain Name 


e res_nclose()--Close Socket and Reset res Structure 


e res_xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res _nsendsigned()--Send Authenticated 
Domain Query or Update 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_nsendsigned(state* res, 
const unsigned char *query_buffer, 
int query_buffer_length, 
ns_tsig_key * key, 
unsigned char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nsendsigned() function is similar to res_nsend() but it uses the specified key to create a transaction 
signature (TSIG) to sign the query or update packet and to authenticate the response. 


Parameters 


res 


(Input) The pointer to the state structure. 


query_buffer 
(Input) The pointer to the query or update message. 


query_buffer_length 
(Input) The length of query_buffer. 


key 


(Input) The pointer to the key to use for authentication. This key must exist on the name server. 


answer_buffer 


(Output) The pointer to where the response is stored. 


answer_buffer_length 


(Input) The size of the answer_buffer. 


Authorities 


No authorization is required. 


Return Value 


res_nsendsigned() returns an integer. Possible values are: 


e@ n (successful), where n is the actual size of the answer returned. 


e -1 (unsuccessful) 


e@ -ns_r_badkey (unsuccessful) The key was invalid or the signing failed. 


e NS_TSIG_ERROR_NO_SPACE (unsuccessful) The message buffer was too small to add the 


TSIG. 


Error Conditions 


When the res_nsendsigned() function fails, res_nsendsigned() can set errno to one of the following: 


[ECONNREFUSED] Not able to connect to a server. 


[ECONVERT] 


[EFAULT] 


[EINVAL] 


[EMSGSIZE] 


Either the input packet could not be translated to ASCII or the answer received 
could not be translated to the coded character set identifier (CCSID) currently in 
effect for the job. 


The system detected a pointer that was invalid while attempting to access an 
input pointer. 


One of the following reasons: 
e An invalid length or NULL pointer was passed to res_nsendsigned() or 
e The res appears to be initialized but the reserved field is not set to zeros. 


Note: No attempt is made to initialize the res structure if it was initialized 
previous to the res_nsendsigned() being issued. 


The message buffer was too small to add the TSIG. The return value was 
NS_TSIG_ERROR_NO_SPACE. 


[ENOTTY] The message or reply couldn't be verified. See extended_error in the res 


structure: 
NS_TSIG_ERROR_FORMERR The message is malformed 
NS_TSIG_ERROR_NO_TSIG The message does not contain a TSIG 


record 


NS_TSIG_ERROR_ID_MISMATCH | The TSIG original ID field does not 
match the message ID. 


(-ns_r_badkey) Verification failed due to an invalid 
key. 

(-ns_r_badsig) Verification failed due to an invalid 
signature. 

(-ns_r_badtime) Verification failed due to an invalid 
timestamp. 

ns_r_badkey Verification succeeded but the message 


had an error (rcode) of ns_r_badkey. 


ns_r_badsig Verification succeeded but the message 
had an error (rcode) of ns_r_badsig. 


ns_r_badtime Verification succeeded but the message 
had an error (rcode) of ns_r_badtime. 


[ETIMEDOUT] A timeout received from a connected server. 


When the res_nsearch() function fails, h_errno (defined in <netdb.h>) can also be set to one of the 
following: 


HOST_NOT_FOUND Either the input packet could not be translated to ASCII or the answer received 
could not be translated to the coded character set identifier (CCSID) currently in 
effect for the job. 


NO_RECOVERY An invalid length or NULL pointer was passed to res_nsendsigned() or the res 
could not be initialized properly. 


Note: No attempt is made to initialize the res structure if it was initialized 
previous to the res_nsendsigned() being issued. 


Note: There are numerous other values that errno can be set to by the sockets functions that 
res_nsendsigned() calls. The above values are the only values that res_nsendsigned() can specifically set. 
Refer to other sockets functions for the other values. errno is always set in an error condition, but h_errno 
is not necessarily set. 


After receiving an error reply packet, res_nsendsigned() will set the extended_error field in the state 
structure to the last reply return code from the DNS server. See <arpa/nameser.h> for all possible values of 
ns_rcode. 


Usage Notes 


1. res_nsendsigned() sends the query or update to the local name server and handles all timeouts and 
retries. The response packet is stored in answer_buffer. 


2. res_nsendsigned() calls res_ninit() if the res structure has not been initialized. 


3. res_nsendsigned() uses the UDP protocol, except for the following cases in which it uses TCP to 
send the packet. 


o If the RES_USEVC or RES_STAYOPEN bits are set in the options field of the res 
structure. 


o If the configuration from Change TCP/IP Domain (CHGTCPDMN) specifies that the 
server protocol is TCP. 


o. If the truncation bit is set in the packet header on the response from a UDP packet, and 
RES_IGNTC is not set in the res structure. 


4. res_nsendsigned() does not perform iterative queries and expects the name server to handle 
recursion. 


5. res_nsendsigned() assumes that the data passed to it is EBCDIC and is in the default coded 
character set identifier (CCSID) currently in effect for the job. It translates the data from the default 
CCSID currently in effect for the job to ASCII (CCSID 819) before the data is sent out to a name 
server. The response that it receives from the name server is returned in the default CCSID 
currently in effect for the job. 


6. res_nsendsigned() will not use the local cache. It will always send the packet to the server. 


7. When using TSIG, it is important that the QUTCOFFSET system value is set correctly for the local 
time zone. The resolver system and name server timestamps must be within 5 minutes of each other 
(adjusted by the UTC offset) or the authentication will fail with ns_r_badtime. 


Related Information 


e hstrerror()--Retrieve Resolver Error Message 


e res_nclose()--Close Socket and Reset res Structure 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e@ res_hostalias()--Retrieve the host alias 


® res_ninit()--Initialize res Structure 


e res_nmkquery()--Place Domain Query in Buffer 


e@ res_nmkupdate()--Construct an Update Packet 


@ res_nquery()--Send Domain Query 


e@ res_nsearch()--Search for Domain Name 


e@ res_nsend()--Send Buffered Domain Query 


@ res_nupdate(Q--Build and Send Dynamic Updates 


e@ res_xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res nupdate()--Build and Send Dynamic 
Updates 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_nupdate(state* res, 


ns_updrec *update_record 
ns_tsig_key *key) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_nupdate() function separates the linked list of update records into groups so that all records in a 
group will belong to a single zone on the nameserver. It creates a dynamic update packet for each zone and 
sends it to the nameservers for that zone. 


Parameters 


(Input) The pointer to the state structure. 


update_record 
(Input) The pointer to the linked list of update records. 


key 


(Input) The pointer to the key to use for authentication. If it is NULL, no authentication will be 
done. 


The ns_updrec structure is defined in <arpa/nameser.h>. 


struct ns_updrec { 
struct { 
struct ns_updrec *prev, *next; 
} vr_link, r_glink; 


ns_sect r_section; 
char * r_dname; 
ns_class r_class; 
ns_type r_type; 


uint32 bet op col be 


unsigned char * r_data; 


uint32 r_size; 
int32 r_opcode; 
/* The following fields are ignored by the resolver routines */ 
struct databuf * r_dp; 
struct databuf * r_deldp; 
uint32 r_zone; 


}; 


typedef struct ns_updrec ns_updrec; 
r_link and r_glink 


Doubly linked lists of ns_updrec records. res_nupdate() uses r_link as its list of records to process 
and ignores r_glink. res_nmkupdate() uses r_glink as its list of records to process and ignores 
r_link. 


r_section 


See the ns_sect enums in <arpa/nameser.h> for allowed values. 


r_dname,r_class,r_type, r_ttl,r_data, and r_size 


Identify the resource record to the DNS 


r_opcode 


Type of update operation. Valid operations are ns_uop_delete or ns_uop_add 


These fields are ignored by the resolver: r_dp, r_deldp, r_zone. 


Authorities 


No authorization is required. 


Return Value 


res_nupdate() returns an integer. Possible values are: 


e n (successful), where n is the number of zones updated. 


e -! (unsuccessful) 


Error Conditions 


When the res_nupdate() function fails, res_nupdate() can set errno to one of the following: 


[ECONVERT] Either the input packet could not be translated to ASCII or the answer received could 
not be translated to the coded character set identifier (CCSID) currently in effect for the 
job. 


[EFAULT] The system detected a pointer that was invalid while attempting to access an input 


pointer. 


[EINVAL] One of the following reasons: 


e An invalid length or NULL pointer was passed to res_nupdate() or 


e The res appears to be initialized but the reserved field is not set to zeros. 


Note: No attempt is made to initialize the res structure if it was initialized 
previous to the res_nupdate() being issued. 


Note: res_nupdate() calls res_findzonecut(), res_nmkupdate() and res_nsend() or res_nsendsigned() so 
errnos from those routines may also be set. 


Usage Notes 


1. 


res_nupdate() calls res_ninit() if the res structure has not been initialized. 


. res_nupdate() calls res_findzonecut() to find the zone and name server to be updated for each input 


record and sorts the records by zone. Then it makes a zone record for each zone and prepends it to 
the update records. It calls res_nmkupdate() to make the update packet and then calls either 
res_nsend() or res_nsendsigned() to send the packet. Note that since res_nupdate() prepends a new 
zone record, the input records must only contain pre-requisite and update records, not zone records. 


. res_nupdate() assumes that the data passed to it is EBCDIC and is in the default coded character set 


identifier (CCSID) currently in effect for the job. It translates the data from the default CCSID 
currently in effect for the job to ASCII (CCSID 819) before the data is sent out to a name server. 
The response that it receives from the name server is returned in the default CCSID currently in 
effect for the job. 


. res_nupdate() will not use the local cache. It will always send the packet to the server. 


. When using TSIG, it is important that the QUTCOFFSET system value is set correctly for the local 


time zone. The resolver system and name server timestamps must be within 5 minutes of each other 
(adjusted by the UTC offset) or the authentication will fail with ns_r_badtime. 


Related Information 


@ res_nclose()--Close Socket and Reset res Structure 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e res_hostalias()--Retrieve the host alias 


@ res_ninit()--Initialize res Structure 


@ res_nmkquery()--Place Domain Query in Buffer 


@ res_nmkupdate()--Construct an Update Packet 


@ res_nquery()--Send Domain Query 


@ res_nsearch()--Search for Domain Name 


e@ res_nsendQ--Send Buffered Domain Query 


e@ res_nsendsigned(Q--Send Authenticated Domain Query 


e@ res_xlate()--Translate DNS Packets 


API introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


res_query()--Send Domain Query 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_query(char *domain_name, 
int class, 
int type, 
char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_query() function is used to interface to the server query mechanism. 


Parameters 


domain_name 


(Input) The pointer to the domain name. 


class 


(Input) The class of data being looked for. See res_mkquery() or <arpa/nameser.h> for possible 
values. 


type 
(Input) The type of request being made. See res_mkquery() or <arpa/nameser.h> for possible 
values. 


answer_buffer 


(Output) The pointer to an address where the response is stored. 


answer_buffer_length 


(Input) The size of the answer area. 


Authorities 


No authorization is required. 


Return Value 


res_query() returns an integer. Possible values are: 


e -! (unsuccessful) 


e@ n (successful), where n is the actual size of the answer returned. 


Error Conditions 


When the res_query() function fails, errno can be set to one of the following: 
[EFAULT] The system detected a pointer that was invalid while attempting to access an input pointer. 


[EINVAL] The _res appears to be initialized but the reserved field is not set to zeros. 


When the res_query() function fails, h_errno (defined in <netdb.h>) can be set to one of the following: 


[HOST_NOT_FOUND] The domain name specified by the domain_name parameter was not found. 
The return code in the response packet was NXDOMAIN. 


[TRY_AGAIN] Either the name server is not running or the name server returned SERVFAIL 
in the response packet. 


[NO_RECOVERY] An unrecoverable error has occurred. Either the domain name could not be 
compressed because it was invalid or the name server returned FORMERR, 
NOTIMP, or REFUSED. 


[NO_DATA] The domain name exists but there is no data of the requested type. 


Usage Notes 


1. res_query() makes a query packet by calling res_mkquery(), sends the query by calling res_send(), 
and makes preliminary checks on the reply. The reply message is left in answer_buffer. 


2. res_query() calls res_init() if the _res structure has not been initialized. 
3. res_query() expects EBCDIC data as input. The output from res_query() is also EBCDIC. 


4. In a thread-enabled environment, the _res structure is shared among all threads within a process. 


Related Information 


e hstrerror()--Retrieve Resolver Error Message 


@ res_nquery()--Send Domain Query 


e res_hostalias()--Retrieve the host alias 


@ res_init()--Initialize res Structure 


@ res_mkquery()--Place Domain Query in Buffer 


e@ res_close()--Close Socket and Reset _res Structure 


@ res_search()--Search for Domain Name 


@ res_send(Q--Send Buffered Domain Query 


e res_xlate()--Translate DNS Packets 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


res_search()--Search for Domain Name 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_search(char *domain_name, 
int class, 
int type, 
char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_search() function is used to make a query message and wait for a response. 


Parameters 


domain_name 


(Input) The pointer to the domain name. 


class 


(Input) The class of data being looked for. See res_mkquery() or <arpa/nameser.h> for possible 
values. 


type 
(Input) The type of request being made. See res_mkquery() or <arpa/nameser.h> for possible 
values. 


answer_buffer 


(Output) The pointer to an address where the response is stored. 


answer_buffer_length 


(Input) The size of the answer area. 


Return Value 


res_search() returns an integer. Possible values are: 


e -! (unsuccessful) 


e@ n (successful), where n is the actual size of the answer returned. 


Authorities: 


Authorization of *R (allow access to the object) to the host aliases file specified by the HOSTALIASES 
environment variable. 


You also need *X authority to each directory in the path of the host aliases file. 


Error Conditions 


When the res_search() function fails, errno can be set to one of the following: 


[EACCES] Permission denied. The process does not have the appropriate privileges to the host aliases 
file specified by the HOSTALIASES environment variable. 


[EFAULT] The system detected a pointer that was invalid while attempting to access an input pointer. 


[EINVAL] The _res appears to be initialized but the reserved field is not set to zeros. 


When the res_search() function fails, h_errno (defined in <netdb.h>) can be set to one of the following: 


[HOST_NOT_FOUND] (Set by the call to res_query() ) The domain name specified by the 
domain_name parameter was not found. The return code in the response 
packet was NXDOMAIN. 


[TRY_AGAIN] Either the name server is not running or the name server returned SERVFAIL 
in the response packet. 


[NO_RECOVERY] (Set by the call to res_query() ) An unrecoverable error has occurred. Either 
the domain name could not be compressed because it was invalid or the name 
server returned FORMERR, NOTIMP, or REFUSED. 


[NO_DATA] (Set by the call to res_query() ) The domain name exists but there is no data of 
the requested type. 


Usage Notes 


1. The res_search() function implements the default and search rules controlled by the 
RES_DEFNAMES and RES_DNSRCH options. res_search() takes the domain name received in 
domain_name, and makes it fully qualified (if it is not already). res_search() also calls res_query(), 
passing it the different domain names to look up, until a successful response is received. 


2. res_search() calls res_init() if the _res structure has not been initialized. 


3. res_search() expects EBCDIC data as input. The output from res_search() is also EBCDIC. 
4. In a thread-enabled environment, the _res structure is shared among all threads within a process. 


5. res_search() will resolve local host aliases to a domain name which are then resolved with a query 
using DNS. See res_hostalias() for more information on aliases. 


Related Information 


e hstrerror()--Retrieve Resolver Error Message 


@ res_nsearch()--Search for Domain Name 


e@ res_hostalias()--Retrieve the host alias 


@ res_init()--Initialize _res Structure 


e@ res_mkquery()--Place Domain Query in Buffer 


@ res_query()--Send Domain Query 


e@ res_close()--Close Socket and Reset _res Structure 


e res_send()--Send Buffered Domain Query 


@ res_xlate()--Translate DNS Packets 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


res _send()--Send Buffered Domain Query or 
Update 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_send(char *query_buffer, 
int query_buffer_length, 
char *answer_buffer, 
int answer_buffer_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_send() function is used to send a query or update message to a name server and retrieve a response. 


Parameters 


query_buffer 
(Input) The pointer to the query or update message. 


query_buffer_length 
(Input) The length of query_buffer. 


answer_buffer 


(Output) The pointer to where the response is stored. 


answer_buffer_length 


(Input) The size of the answer_buffer. 


Authorities: 


No authorization is required. 


Return Value 


res_send() returns an integer. Possible values are: 


e -! (unsuccessful) 


e@ n (successful), where n is the actual size of the answer returned. 


Error Conditions 


When the res_send() function fails, res_send() can set errno to one of the following: 


[ECONNREFUSED] Not able to connect to a server. 


[ECONVERT] Either the input packet could not be translated to ASCII or the answer received 
could not be translated to the coded character set identifier (CCSID) currently in 
effect for the job. 

[EINVAL] One of the following reasons: 


e An invalid length or NULL pointer was passed to res_send() or 
e The _res could not be initialized properly or 
e The _res appears to be initialized but the reserved field is not set to 


Zeros. 


Note: No attempt is made to initialize the _res structure if it was initialized 
previous to the res_send() being issued. 


[ESRCH] No DNS servers were specified in nsadadr. 


[ETIMEDOUT] A timeout received from a connected server. 


When the res_send() function fails, h_errno (defined in <netdb.h>) can also be set to one of the following: 


HOST_NOT_FOUND Either the input packet could not be translated to ASCII or the answer received 
could not be translated to the coded character set identifier (CCSID) currently in 
effect for the job. 


NO_RECOVERY An invalid length or NULL pointer was passed to res_send() or the _res could 
not be initialized properly. 


Note: No attempt is made to initialize the _res structure if it was initialized 
previous to the res_send() being issued. 


Note: There are numerous other values that errno can be set to by the sockets functions that res_send() 
calls. The above values are the only values that res_send() can specifically set. Refer to other sockets 
functions for the other values. errno is always set in an error condition, but h_errno is not necessarily set. 


After receiving an error reply packet, res_send() will set the extended_error field in the state structure to 
the last reply return code from the DNS server. See <arpa/nameser.h> for all possible values of ns_rcode. 


Usage Notes 


1. 


res_send() sends the query or update to the local name server and handles all timeouts and retries. 
The response packet is stored in answer_buffer. 


. res_send() calls res_init() if the _res structure has not been initialized. 


. res_send() uses the UDP protocol, except for the following cases in which it uses TCP to send the 


packet. 


o If the RES_USEVC or RES_STAYOPEN bits are set in the options field of the _res 
structure. 


o If the configuration from Change TCP/IP Domain (CHGTCPDMN) specifies that the 
server protocol is TCP. 


o. If the truncation bit is set in the packet header on the response from a UDP packet, and 
RES_IGNTC is not set in the _res structure. 


. res_send() does not perform interactive queries and expects the name server to handle recursion. 


. res_send() assumes that the data passed to it is EBCDIC and is in the default coded character set 


identifier (CCSID) currently in effect for the job. It translates the data from the default CCSID 
currently in effect for the job to ASCII (CCSID 819) before the data is sent out to a name server. 
The response that it receives from the name server is returned in the default CCSID currently in 
effect for the job. 


. Unless RES_NOCACHE was specified, res_send() checks the cached data for the answer to the 


query (but not for updates). If the answer is found and the time to live has not expired, it is returned 
to the calling program in answer_buffer and no attempt is made to send it on the network. If the 
time to live has expired, the entry is deleted from the cache, and the query is sent on the network. If 
the answer is not found in the cache, res_send() also sends the query on the network. When an 
answer is received from the network, it is placed in cache if it is an authoritative answer and is not 
the result of an inverse query. RES_NOCACHE does not stop answers from being cached. 
Authoritative negative replies, indicating the data does not exist, will also be cached. 


. Ina thread-enabled environment, the _res structure is shared among all threads within a process. 


Related Information 


e hstrerror()--Retrieve Resolver Error Message 


e res_nsend()--Send Buffered Domain Quer 


e res_hostalias()--Retrieve the host alias 


@ res_init()--Initialize _res Structure 


e@ res_mkquery()--Place Domain Query in Buffer 


@ res_query()--Send Domain Query 


@ res_search()--Search for Domain Name 


@ res_close()--Close Socket and Reset _res Structure 


e res_xlate()--Translate DNS Packets 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


res_ xlate()--Translate DNS Packets 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_xlate(int input_ccsid, 
char *input_packet, 
int input_length, 
int output_ccsid, 
char *output_packet, 
int output_length) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The res_xlate() function is used to translate a standard DNS packet between ASCII and EBCDIC. 


Parameters 


input_ccsid 
(Input) The CCSID value of the input packet to be translated. 


input_packet 
(Input) The pointer to where the standard DNS packet to be translated resides. 


input_length 
(Input) The length of input_packet. 


output_ccsid 
(Input) The CCSID value for the output packet. 


output_packet 
(Output) The pointer to where the translated DNS packet will be stored. 


output_length 
(Input) The length of output_packet. 


Authorities 


No authorization is required. 


Return Value 


res_xlate() returns an integer. Possible values are: 


e | (successful) 
e 0 (unsuccessful - translation error) 


e -! (unsuccessful - errors other than translation) 


Error Conditions 


When the res_xlate() function fails, it does not set specific errno or h_errno values. An error occurs under 
the following conditions: 


e NULL pointer(s) passed to the function. 
e Invalid pointer(s) passed to the function. 
e Invalid lengths passed to the function. 


e An invalid packet format encountered. 


Usage Notes 


1. res_xlate() parses through input_packet, determining which fields need translation. The packet is 
copied into output_packet as it is parsed, translating the fields as needed from input_ccsid to 
output_ccsid. If a bad format is encountered or a user-supplied length is too small, res_xlate() 
returns a -1. 


2. If there is an error in the translation of input_packet from input_ccsid to output_ccsid, res_xlate() 
returns a value of 0 to the caller. 


3. res_xlate() expects a value of 819 (ASCII) for either the input or output coded character set 
identifier (CCSID). If translation from an EBCDIC CCSID is to occur, the output CCSID needs to 
be set to 819. input_packet is then translated to ASCII, and the result is placed in output_packet If 
translation to an EBCDIC CCSID is to occur, the input CCSID needs to be set to 819. input_packet 
is then translated from ASCII to the EBCDIC CCSID specified in output_ccsid, and the result is 
placed in output_packet. 


res_xlate() returns unsuccessfully with a value of -1 if CCSID 819 is not used for either 
input_ccsid or output_ccsid. Also, if both input_ccsid and output_ccsid values are 819, res_xlate() 
returns a -1. 


4. Ina thread-enabled environment, the _res is shared among all threads within a process. 


Related Information 


e hstrerror()--Retrieve Resolver Error Message 


e res_hostalias()--Retrieve the host alias 


@ res_init()--Initialize _res Structure 


e res_mkquery()--Place Domain Query in Buffer 


@ res_query()--Send Domain Query 


@ res_search()--Search for Domain Name 


e res_send()--Send Buffered Domain Query 


e res_close()--Close Socket and Reset _res Structure 


e res_findzonecut()--Find the Enclosing Zone and Servers 


e res_hostalias()--Retrieve the host alias 


@ res_ninit()--Initialize res Structure 


@ res_nclose()--Close Socket and Reset res Structure 


e@ res_nmkquery()--Place Domain Query in Buffer 


e@ res_nmkupdate()--Construct an Update Packet 


@ res_nquery(Q--Send Domain Query 


@ res_nsearch()--Search for Domain Name 


e res_nsend()--Send Buffered Domain Quer 


e res_nsendsignedQ--Send Authenticated Domain Query 


e res_nupdate()--Build and Send Dynamic Updates 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


sethostent()--Open Host Database 


Syntax 


#include <netdb.h> 


void sethostent (int stay_open) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The sethostent() function is used to prepare for sequential access to the host database file. sethostent() 
opens the file and repositions the file marker to the beginning of the file. In addition, sethostent() affects 
what type of transport service (connectionless versus connection-oriented) is to be used when 
gethostbyname() and gethostbyaddr() need to retrieve host information from the domain name server. 


Parameters 


int stay_open 


(Input) Specifies whether to leave the database file open after each call to gethostbyname() and 


gethostbyaddr(). A nonzero value results in the database file being left open. Also, a nonzero value 


results in the use of a connection-oriented transport service (for example, TCP) being used by 
gethostbyname() and gethostbyaddr() when host information is to be obtained from the domain 
name server. 


Authorities 


No authorization is required. 


Error Conditions 


When sethostent() fails, h_errno (defined in <netdb.h>) can be set to one of the following: 


NO_RECOVERY An unrecoverable error has occurred. 


Usage Notes 


1. #The iSeries Navigator or the * following CL commands can be used to access the host database 
file: 


ADDTCPHTE (Add TCP/IP Host Table Entry 
RMVTCPHTE (Remove TCP/IP Host Table Entry) 
CHGTCPHTE (Change TCP/IP Host Table Entry) 
RNMTCPHTE (Rename TCP/IP Host Table Entry) 
MRGTCPHT (Merge TCP/IP Host Tables) 


O 0 0 0 0 


2. Do not use the sethostent() function in a multithreaded environment. See the multithread alternative 
sethostent_r() function. 


3. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the sethostent() API is mapped to 
qso_sethostent98( dK 


Related Information 


@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e gethostbyaddr()--Get Host Information for IP Address 


e gethostbyname()--Get Host Information for Host Name 


e endhostent()--Close Host Database 


e gethostent()--Get Next Entry from Host Database 


API introduced: V3R1 


Top | UNIX-Type APIs | APIs by category 


sethostent_r()--Open Host Database 


Syntax 


#include <netdb.h> 


int sethostent_r(int stay_open, 
struct hostent_data *hostent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The sethostent_r() function is used in preparation for sequential access to the host database file. The 
sethostent_r() function opens the file and repositions the file marker to the beginning of the file. In addition, 
this call affects what type of transport service (connectionless versus connection-oriented) that is to be used 
when gethostbyname_r() and gethostbyaddr_r() need to retrieve host information from the domain name 
server. 


Parameters 


int stay_open (input) 


Specifies whether to leave the database file open after each call to gethostbyname_r() and 
gethostbyaddr_r(). A non-zero value will result in the database file being left open. Also, a 
non-zero value will result in the use of a connection-oriented transport service (for example, TCP) 
being used by gethostbyname_r() and gethostbyaddr_r() when host information is to be obtained 
from the domain name server. 


struct hostent_data *hostent_data_struct_addr (input/output) 


Specifies the pointer to the hostent_data structure, which is used to pass and preserve results 
between function calls. The field host_control_blk in the hostent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire hostent_data structure must be initialized to hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The sethostent_r() function returns an integer. Possible values are: 
e -1 (unsuccessful call) 


e@ 0 (successful call) 


The struct hostent_datadenoted by hostent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the sethostent_r() function fails, h_errno (defined in <netdb.h>) can be set to: 


[NO_RECOVERY] An unrecoverable error has occurred. 


When the sethostent_r() function fails, errno can be set to: 


[EINVAL] The hostent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure hostent_data. 


Usage Notes 


2The iSeries Navigator or the * following CL commands can be used to access the host database file: 
e ADDTCPHTE (Add TCP/IP Host Table Entry) 
@ RMVTCPHTE (Remove TCP/IP Host Table Entry) 
e CHGTCPHTE (Change TCP/IP Host Table Entry) 
e@ RNMTCPHTE (Rename TCP/IP Host Table Entry) 
e@ MRGTCPHT (Merge TCP/IP Host Tables) 


Related Information 


e gethostbyaddr_rQ--Get Host Information for IP Address 


e gethostbyname_r()--Get Host Information for Host Name 


e endhostent_r()--Close Host Database 


e gethostent_r(Q--Get Next Entry from Host Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


setnetent()--Open Network Database 


Syntax 


#include <netdb.h> 


void setnetent (int stay_open) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The setnetent() function is used to prepare for sequential access to the network database file. setnetent() 
opens the file and repositions the file marker to the beginning of the file. 


Parameters 
stay_open 


(Input) A value that indicates whether to leave the database file open after each getnetbyname() and 
getnetbyaddr(). A nonzero value will result in the database file being left open. 


Authorities 


No authorization is required. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the network 
database file: 


Oo WRKNETTBLE (Work with Network Table Entries) 
o ADDNETTBLE (Add Network Table Entry) 
oO RMVNETTBLE (Remove Network Table Entry) 


2. Do not use the setnetent() function in a multithreaded environment. See the multithread alternative 
setnetent_r() function. 


3. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the setnetent() API is mapped to 
qso_setnetent98().%& 


Related Information 


e@ = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface 


e@ getnetbyaddr()--Get Network Information for IP Address 


@ getnetbyname()--Get Network Information for Domain Name 


e@ getnetent()--Get Next Entry from Network Database 


@ endnetent()--Close Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


setnetent_r()--Open Network Database 


Syntax 


#include <netdb.h> 


int setnetent_r(int stay_open, 
struct netent_data 
*netent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The setnetent_r() function is used in preparation for sequential access to the network database file. The 
setnetent_r() function opens the file and repositions the file marker to the beginning of the file. 


Parameters 


int stay_open (input) 


Specifies whether to leave the database file open after each call to getnetbyname_r() and 
getnetbyaddr_r(). A non-zero value will result in the database file being left open. 


struct netent_data *netent_data_struct_addr (input/output) 


Specifies the pointer to the netent_data structure, which is used to pass and preserve results 
between function calls. The field net_control_blk in the netent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire netent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The setnetent_r() function returns a pointer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct netent_datadenoted by netent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the setnetent_r() function fails, errno can be set to: 


[EINVAL] The netent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action see the description for structure netent_data. 


Usage Notes 


2The iSeries Navigator or the *& following CL commands can be used to access the network database file: 
@e WRKNETTBLE (Work with Network Table Entries) 
e ADDNETTBLE (Add Network Table Entry) 
e RMVNETTBLE (Remove Network Table Entry) 


Related Information 


e@ getnetent_rQ--Get Next Entry from Network Database 


e@ getnetbyaddr_rQ--Get Network Information for IP Address 


e@ getnetbyname_r()--Get Network Information for Domain Name 


e endnetent_r()--Close Network Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


setprotoent()--Open Protocol Database 


Syntax 


#include <netdb.h> 


void setprotoent (int stay_open) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The setprotoent() function is used to prepare for sequential access to the protocol database file. 
setprotoent() opens the file and repositions the file marker to the beginning of the file. 


Parameters 
stay_open 


(Input) A value that indicates whether to leave the database file open after each getprotobynumber() 
and getprotobyname(). A nonzero value results in the database file being left open. 


Authorities 


No authorization is required. 


Usage Notes 


1. The iSeries Navigator or the * following CL commands can be used to access the protocol 
database file: 


Oo WRKPCLTBLE (Work with Protocol Table Entries) 
o ADDPCLTBLE (Add Protocol Table Entry) 
Oo RMVPCLTBLE (Remove Protocol Table Entry) 


2. Do not use the setprotoent() function in a multithreaded environment. See the multithread 
alternative setprotoent_r() function. 


3. 2*When you develop in C-based languages and an application is compiled with the 
_XOPEN_SOURCE macro defined to the value 520 or greater, the setprotoent() API is mapped to 


qso_setprotoent98().%& 


Related Information 


e = _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface*& 


@ getprotobyname()--Get Protocol Information for Protocol Name 


@ getprotobynumber()--Get Protocol Information for Protocol Number 


@ getprotoent()--Get Next Entry from Protocol Database 


e endprotoent()--Close Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


setprotoent_r()--Open Protocol Database 


Syntax 


#include <netdb.h> 


int setprotoent_r(int stay_open, 
struct protoent_data *protoent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The setprotoent_r() function is used in preparation for sequential access to the protocol database file. The 
setprotoent_r() function opens the file and repositions the file marker to the beginning of the file. 


Parameters 


int stay_open (input) 


Specifies whether to leave the database file open after each call to getprotobynumber_r() and 
getprotobyname_r(). A non-zero value will result in the database file being left open. 


struct protoent_data *protoent_data_struct_addr (input/output) 


Specifies the pointer to the protoent_data structure, which is used to pass and preserve results 
between function calls. The field proto_control_blk in the protoent_data structure must be 
initialized with hexadecimal zeros before its initial use. If compatibility with other platforms is 
required, then the entire protoent_data structure must be initialized with hexadecimal zeros before 
initial use. 


Authorities 


No authorization is required. 


Return Value 


The setprotoent_r() returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct protoent_data denoted by protoent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the setprotoent_r() function fails, errno can be set to: 


[EINVAL] The protoent_data structure was not properly initialized with hexadecimal zeros before 
initial use. For corrective action, see the description for structure protoent_data. 


Usage Notes 


2The iSeries Navigator or the *& following CL commands can be used to access the protocol database file: 
e WRKPCLTBLE (Work with Protocol Table Entries) 
e ADDPCLTBLE (Add Protocol Table Entry) 
e RMVPCLTBLE (Remove Protocol Table Entry) 


Related Information 


@ getprotobynumber_r()--Get Protocol 


e@ getprotobyname_r()--Get Protocol Information for Protocol Name 


e endprotoent_rQ--Close Protocol Database 


e getprotoent_r()--Get Next Entry from Protocol Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


setservent()--Open Service Database 


Syntax 


#include <netdb.h> 


void setservent (int stay_open) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: No; see Usage Notes. 


The setservent() function is used to prepare for sequential access to the service database file. setservent() 
opens the file and repositions the file marker to the beginning of the file. 

Parameters 

stay_open 


(Input) A value that indicates whether to leave the database file open after each getservbyname() 
and getservbyport(). A nonzero value results in the database file being left open. 


Authorities 


No authorization is required. 


Usage Notes 


1. 2The iSeries Navigator or the *& following CL commands can be used to access the services 
database file: 


Oo WRKSRVTBLE (Work with Service Table Entries) 
o ADDSRVTBLE (Add Service Table Entry) 


Oo RMVSRVTBLE (Remove Service Table Entry) 


2. Do not use the setservent() function in a multithreaded environment. See the multithread alternative 
setservent_r() function. 


3. 2*When you develop in C-based languages and an application is compiled with the 


_XOPEN_SOURCE macro defined to the value 520 or greater, the setservent() API is mapped to 
qso_setservent98().& 


Related Information 


e = XOPEN SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface®® 


e@ getservbyname()--Get Port Number for Service Name 


@ getservbyport()--Get Service Name for Port Number 


@ getservent()--Get Next Entry from Service Database 


e endservent()--Close Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


setservent_r()--Open Service Database 


Syntax 


#include <netdb.h> 


int setservent_r(int stay_open, 
struct servent_data *servent_data_struct_addr) 


Service Program Name: QSOSRV2 


Default Public Authority: *USE 


Threadsafe: Yes 


The setservent_r() function is used in preparation for sequential access to the service database file. The 
setservent_r() function opens the file and repositions the file marker to the beginning of the file. 


Parameters 


int stay_open (input) 


Specifies whether to leave the database file open after each call to getservbyname_r() and 
getservbyport_r(). A non-zero value will result in the database file being left open. 


struct servent_data *servent_data_struct_addr (input/output) 


Specifies the pointer to the servent_data structure, which is used to pass and preserve results 
between function calls. The field serve_control_blk in the servent_data structure must be initialized 
with hexadecimal zeros before its initial use. If compatibility with other platforms is required, then 
the entire servent_data structure must be initialized with hexadecimal zeros before initial use. 


Authorities 


No authorization is required. 


Return Value 


The setservent_r() function returns an integer. Possible values are: 
e -! (unsuccessful call) 


e 0 (successful call) 


The struct servent_datadenoted by servent_data_struct_addr is defined in <netdb.h>. 


Error Conditions 


When the setservent_r() function fails, errno can be set to: 


[EINVAL] The servent_data structure was not properly initialized to hexadecimal zeros before initial 
use. For corrective action, see the description for structure servent_data. 


Usage Notes 


2The iSeries Navigator or the *& following CL commands can be used to access the services database file: 
e WRKSRVTBLE (Work with Service Table Entries) 
e ADDSRVTBLE (Add Service Table Entry) 
@e RMVSRVTBLE (Remove Service Table Entry) 


Related Information 


@ getservbyname_r()--Get Port Number for Service Name 


@ getservbyport_rQ--Get Service Name for Port Number 


e endservent_r()--Close Service Database 


e@ getservent_r()--Get Next Entry from Service Database 


API introduced: V4R2 


Top | UNIX-Type APIs | APIs by category 


_getlong()--Get Long Byte Quantities 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


unsigned long 
_getlong(unsigned char *message_pointer) 


Threadsafe: Yes 


The _getlong() function is used to retrieve an unsigned long byte quantity. 


Parameters 


message_pointer 


(Input) The pointer where the long integer is to be received from. 


Return Value 


_getlong() returns a 32-bit integer from where message_pointer is pointing. 


Usage Notes 


1. DNS packets have fields that are unsigned long integers (for example, TTL and serial number). 
_getlong() picks these unsigned long integers out of a DNS packet and returns them. 


Related Information 


e _getshort()--Get Short Byte Quantities 


e _putlong()--Put Long Byte Quantities 


e@ _putshort()--Put Short Byte Quantities 


API introduced: V3R1 
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_getshort()--Get Short Byte Quantities 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


unsigned short 
_getshort (unsigned char *message_pointer) 


Threadsafe: Yes 


The _getshort() function is used to retrieve an unsigned short byte quantity. 


Parameters 


message_pointer 


(Input) The pointer where the short integer is to be received from. 


Return Value 


_getshort() returns a 16-bit integer from where message_pointer is pointing. 


Usage Notes 


1. DNS packets have fields that are unsigned short integers (for example, type, class, and data length). 
_getshort() picks these unsigned short integers out of a DNS packet and returns them. 


Related Information 


e _getlong(--Get Long Byte Quantities 


e _putlong()--Put Long Byte Quantities 


e@ _putshort()--Put Short Byte Quantities 


API introduced: V3R1 
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_putlong()--Put Long Byte Quantities 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


void _putlong(unsigned long long_integer, 
unsigned char *message_pointer) 


Threadsafe: Yes 


The _putlong() function is used to put an unsigned long byte quantity into a byte stream. 


Parameters 


long_int 
(Input) The 32-bit integer to be put into the byte stream. 


unsigned char *message_pointer 


(Input) The pointer to where the long_integer is to be put. 


Return Value 


_putlong() puts a 32-bit integer into message_pointer. 


Usage Notes 


DNS packets have fields that are unsigned long integers (for example, TTL and serial number). _putlong() 
is generally used to put these fields into a DNS packet. 


Related Information 


e _getlong()--Get Long Byte Quantities 


e _getshort()--Get Short Byte Quantities 


e _putshort()--Put Short Byte Quantities 


API introduced: V3R1 
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_putshort()--Put Short Byte Quantities 


Syntax 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


void _putshort(unsigned short short_integer, 
unsigned char *message_pointer) 


Threadsafe: Yes 


The _putshort() function is used to put an unsigned short byte quantity into a byte stream. 


Parameters 


unsigned short short_int 


(Input) The 16-bit integer to be put into the byte stream. 


unsigned char *message_pointer 


(Input) The pointer to where the short_integer is to be put. 


Return Value 


_putshort() puts a 16-bit integer into message_pointer. 


Usage Notes 


DNS packets have fields that are unsigned short integers (for example, type, class, and data length). 
_putshort() is generally used to put these fields into a DNS packet. 


Related Information 


e _getlong(--Get Long Byte Quantities 


e@ _getshortQ--Get Short Byte Quantities 


e _putlong()--Put Long Byte Quantities 


API introduced: V3R1 
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Debugging IP over SNA Configurations 


Two commands can be helpful in debugging IP over SNA configurations: 


e The Start Mode (STRMOD) CL command can help you determine if your SNA configuration is 
correct. As input to the STRMOD command, you need the remote location name. You can 
determine the remote location name from the destination IP address by using the Convert IP over 
SNA Interface (CVTIPSIFC) command. The message you receive when STRMOD completes tells 
you whether it was successful. 


e The TCP/IP FTP command can help you determine if your AnyNet configuration is correct. If you 
get the User prompt, the AnyNet configuration is correct. 


Note: When FTP fails, it does not give a detailed reason for the failure. To get a detailed reason, 
you should run a sockets program that reports the value for errno when the failure occurs. 


Figure 1-21. Common IP over SNA Configuration Errors 


[Sockets Error (value of errno) [Possible Causes 


EHOSTUNREACH . Missing ADDIPSLOC command on client system. 

2. Missing ADDIPSIFC command on client system. 

3. Type of service points to a non-existent mode description on 
client system. 

4. ADDIPSLOC command on client system resulted in a 
location name that is not found. 

5. ADDIPSLOC command on client system resulted in a 
location name that is on a non-APPC device description. 


EADDRNOTAVAIL . AnyNet not active on client system (ALWANYNET attribute 
set to *NO), but TCP is started. 
2. Mode could not be added to device on client system. 


ee . AnyNet not active on client system (ALWANYNET attribute 


ECONNREFUSED . AnyNet not active on client system (ALWANYNET attribute 
set to *NO). 
2. listen() not active on server system. 


set to *NO), and TCP is not started. 


ECONNABORTED 


ETIMEDOUT 


. Line error 


. Device/controller/line varied off on client or server system 


while in use. 


. User not authorized to APPC device description object on 


server system. 


. ADDIPSLOC command on client system points to a location 


name that does not exist or is on a system that is not 
responding in the APPN network. 


. Messages (especially inquiry messages) on message queue 


EACCES 


QSYSOPR are waiting for a reply. 


. User not authorized to port on client system. 


. User not authorized to APPC device description object on 
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client system. 


Header Files for UNIX-Type Functions 


Programs using the UNIX-type functions must include one or more header files that contain information 
needed by the functions, such as: 


e Macro definitions 
e Data type definitions 
e Structure definitions 
e Function prototypes 
The header files are provided in the QS YSINC library, which is optionally installable. Make sure 


QSYSINC is on your system before compiling programs that use these header files. For information on 
installing the QSYSINC library, see Data structures and the QSYSINC Library. 


The table below shows the file and member name in the QS YSINC library for each header file used by the 
UNIX-type APIs in this publication. 


Name of File in 
Name of Header File QSYSINC Name of Member 


[| arpa/ineth [| arpa/ineth [ ARPA [INET 


a 
a * 

tik | | so 
[  —sbseerrch CEC A~<“‘i‘~*Y:S*é‘éiBSEERRR 
[ss direnth [CM Rs—~<“i«i‘Cé«zYS)~OCéIRENT 
[ emoh [| H [ERRNO] | 
[_eph | SOS 

| evinttypes. h | | TNS 
ee ee ee 
[| %netinet/iemp6.h NETINE |  ICMP6& 
[| netinetinh NETINET [| WN 
| netinet/ip_icmp.h NETINET [|  IPICMP 


mo) oo) eo) eo) a) ee} ee} ey] 


| netinet/ip.h NETINET | IP 
| 2’netinet/ip6.h NETINET | IP6& 
| netinet/tcp.h NETINET TCP 


| netinet/udp.h NETINET UDP 

[netns/idph = | 0S NETNS) [CIDP 
[netns/ipxh = |S NETNS) [CPX 
[so netns/ns-h | NETNS) [CONST 
[so netns/sp-b |S NETNS) [SP 
[netrouteh = [)CNET)=—~<C;«é‘L”)~Ss*'<‘éROUTEECi:*s 
[—snettel/telLh «= sis[))sSNETTEL =o [)ti‘<‘STENRES—“( isis 


an 


[  oosh fC OS2 

[|  —sosddefh fC ASE S2DEF 
[ pwd fC PWD 

[0 gh fH QLG 

| —s qpOlfloph fs QPOLFLOP 
| Bqp0limih | | QPOLIRNLE 

| 2>qpOlror.h | | QPOLROR& 

|  qpOzolsm-h fC HH—C*ST ss QPOZOLSM 
| — qpOztrech fC QPOZTRE 
|  qpOztrmlh [| CSTs QPOZTRML 
| #qsoasync.h | | QSOASYNC% 
| qtnxaapi.h | QTNXAAPI 
[ qtnxadtph fC H——CSE ss QQTNXADTP 
|  qtomeapih sf] CM ™—C~@TSsC QQOMEEAP 


TRIG 


| qtossapi.h | H | QTOSSAPI 
| resolv.h | H | RESOLVE 


an 


| semaphore.h | | SEMAPHORE 


[signal | CMHC SIGNAL 
[|  spawnh Cf CM ™~“<~S SPAWN 
[ssh fA SSL 

| sysferrnoh = fC H™:~iT SC ERRNOU 
[| sysfioctLh SYS [|  IOCTL 
| ——ssys/ipeh SYS [ woe 


| sys/layout.h | H | LAYOUT 
| sys/limits.h | H | LIMITS 


| —ssys/msg-ho SYS MSG 

[| sys/param.h SYS [ PARAM 
| #*sys/resource.h SYS | RESOURCE® 

| —ssys/sem-h SYS SEM 

| sys/setimp.h SYS | ‘SETIMP 
| sys/shm.h SYS SHM 

[| sys/signalh SYS [ SIGNAL 
[| _sys/socketh SYS [SOCKET 
[| —sys/stath SYS [ STAT” 


| sys/statvfs.h SYS | STATVFS 


| —ssysfimeh SYS [| TIME 
[| sys/types.b SYS [TYPES si 
| —ssys/uio.h SYS UIO 

[ sys SYS [ UN 
| —ssys/waith SYS | WAIT 
| Sulimit.h H | ULIMIT*& 

[| sounistdh fC HSE UNISTD 
[  soutimeh fC UTIME 


You can display a header file in QS YSINC by using one of the following methods: 


e Using your editor. For example, to display the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(5) 


e Using the Display Physical File Member command. For example, to display the sys/stat.h header 
file, enter the following command: 


DSPPFM FILE(QSYSINC/SYS) MBR(STAT) 


You can print a header file in QSYSINC by using one of the following methods: 


e Using your editor. For example, to print the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION (6) 
e Using the Copy File command. For example, to print the sys/stat.h header file, enter the following 


command: 


CPYF FROMFILE(QSYSINC/SYS) TOFILE(*PRINT) FROMMBR (STAT) 


Symbolic links to these header files are also provided in directory /QIBM/include. 
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Errno Values for UNIX-Type Functions 


Programs using the UNIX-type functions may receive error information as errno values. The possible 
values returned are listed here in ascending errno value sequence. 


[Name [Value [Test 

~——— a ee domain error occurred in a math 
function. 

[ERANGE = GE [300200 A [Arangeerror occurred. = error [Arangeerror occurred. = 

—| C _— Data was truncated on an input, output, or 
update operation. 

EN [ENOTOPEN [3004 [Fileisnotopen. is not [Fileisnotopen. 


—— OTREAD — [File i is not opened for read operations. 
EIO [3006 [Input/output error. 


EN [ENODEV [3007 N [Nosuchdevice. [Nosuchdevice. device. 

ae —_ Cannot get single character for files 
opened for record I/O. 

EN [ENOTWRITE [30090 [File is not opened for write operations. is not [File is not opened for write operations. for write operations. 


a —— [The stdin stream cannot be opened. 
[ESTDOUT [3011 [The stdout stream cannot be opened. 


[ESTDERR [30120 [The stderr stream cannot be opened. stderr stream cannot be [The stderr stream cannot be opened. 

_—| a The positioning parameter in fseek is not 
correct. 

[EBADNAME AME [30140 [The object name specified is not correct. — [The object name specified is not correct. — name specified is not correct. 


a ——! The type variable specified on the open 
function is not correct. 


[EBADPOS 3017s [The position specifier is not correct. position [The position specifier is not correct. is not correct. 


17 
EN a — There is no record at the specified 
position. 
ENUMMBRS 3019 Attempted to use ftell on multiple 
members. 
ENUMRECS 3020 The current record position is too long for 
ftell. 
EINVAL 3021 The value specified for the argument is not 
correct. 
EBADFUNC 3022 Function parameter in the signal function 
is not set. 
[302500 


EN [ENOENT T No [No such path or directory, = [No such path or directory, = or directory. 


FoR? ——— ht’ —— ae 
[EPERM  =——<CS~s«LB27_~——SSC«*d Phe Oplerationn is not permitted. = 
[EBADDATA  ——s[3028——Ss[Meessage dataisnotvalid. = 
[EBUSY ==—=«S(38029—s Resource busy, 
[EBADOPT —s*(3040 = Option specified is not valid. 
[ENOTUPD ~—s*([3041 =~‘ File is not opened for update operations. 
[ENOTDLT ~—*[3042. [File is not opened for delete operations. 


EPAD 3043 The number of characters written is 
shorter than the expected record length. 

EBADKEYLN 3044 A length that was not valid was specified 
for the key. 

EPUTANDGET 3080 A read operation should not immediately 
follow a write operation. 

EGETANDPUT 3081 A write operation should not immediately 
follow a read operation. 

[EIOERROR [3101 [A nonrecoverable I/O error occurred. 

[EIORECERR [3 102 [A recoverable I/O error occurred. 

[EACCES [3401 [Permission denied. 


[EN OTDIR [3403 [N ot a directory. 
[ENOSPC [3404 [No space is available. 


[EXDEV [3405 Improper link, [Improperlink, 


[34050 
aa_— 3406 Operation would have caused the process 
to be suspended. 
EWOULDBLOCK 3406 Operation would have caused the process 
to be suspended. 
[3407 


[EINTR [3407 SS s‘[Interrupted function call. [Interrupted function call. call. 


ee— 3408 The address used for an argument was not 
correct. 


[ETIME [3409 [3409 [Operation timedout. [Operation timedout. out. 
—_——— [3415 0 No [No such device oraddress. device [No such device oraddress. address. 
SEs i Pa 
failure 
[ERECURSE [3419 [Recursive attempt rejected. = attempt [Recursive attempt rejected. = 
 ORNESE Si —— see 
[EADDRNOTAVAIL [342200 [Address is notavailable. = [Address is notavailable. = not available. 
ESINOSUORT > pean type of socket is not supported in this 
protocol family. 
[EALREADY [342300 [3423 [Operation is already in progress. = is already in progress. 
REE ABORTED [34240000 [Connection ended abnormally. ended [Connection ended abnormally. 
25 


ECONNRTUSED — aS rma ba tn te 
connect operation 
i ae ce 
reset by that socket 
[EDESTADDRREQ. [3427 00 [3427 | Operation requires destination address. requires [Operation requires destination address. address. 
[EHOSTDOWN [3428s {Ar remote host is notavailable. 
[EHOSTUNREACH [3429 ‘A route to the remote host is not available. 
[EINPROGRESS —[3430. Ss |Operationin progress. = 
[EISCONN «(3431s {A connection has already been established. 
[EMSGSIZE «(3432s [Message size isoutofrange. 
[ENETDOWN  ——s[3433.—s*[ The network currently is not available. 


ENETRESET 3434 A socket is connected to a host that is no 
longer available. 


[ENETUN REACH [3435 [Cannot reach the destination network. 

ENOBUFS 3436 There is not enough buffer space for the 
requested operation. 

ENOPROTOOPT 3437 The protocol does not support the 

specified option. 

ENOTCONN 3438 Requested operation requires a 
connection. 

ENOTSOCK 3439 The specified descriptor does not 
reference a socket. 

[EN OTSUP [3440 [Operation is not supported. 

[EOPN OTSUPP [3440 [Operation is not supported. 


EPFNOSUPPORT 3441 The socket protocol family is not 
supported. 

EPROTONOSUPPORT |3442 No protocol of the specified type and 
domain exists. 

EPROTOTYPE 3443 The socket type or protocols are not 
compatible. 

ERCVDERR 3444 An error indication was sent by the peer 
program. 


[ESHUTDOWN [3445 [Cannot send data after a shutdown. 
[ESOCKTN OSUPPORT [3446 [The specified socket type is not supported. 


ETIMEDOUT 3447 A remote host did not respond within the 
timeout period. 

EUNATCH 3448 The protocol required to support the 
specified address family is not available at 
this time. 


[EBADF = =—S—=«&;3'45——SsDescriptorisnot valid, 
[EMFILE  =—S*[3452,—S——Ss {Too many open files for this process. 
[ENFILE =——=S&3453. Ss [Too many open files inthe system. 
EPIPE == ~—«*(3455, ss (Brokenpipe. 
[ECANCEL =——s«[3456.———s|Operationcancelled. = 
[EEXIST =———s«*(3'KST_—— sie exists, 
[EDEADLK =——s*[3459_ Resource deadlock avoided. 
[ENOMEM ——s«[3460—Ss« Storage allocation request failed. = 
62 


a 34 The synchronization object no longer 
exists because the owner is no longer 
running. 

EDESTROYED 3463 The synchronization object was destroyed, 
or the object no longer exists. 

[ETERM [3464 00—CO [3464 Operation was terminated. = was [Operation was terminated. = 


aes —— OENT1 [3 465 [N o such file or directory. 


ENOEQFLOG 3466 Object is already linked to a dead 
ones sag 


[EEMPTYDIR [3 467 [Directoryisempty. = is empty. 


EMLINK 3468 Maximum link count for a file was 
exceeded. 


ESPIPE  =—~SC~«&346—— “Seek request is not supported for object. 
[ENOSYS —————=«*3470.—S—SSs|Function not implemented. = 
[EISDIR ——i(ass—t*é«*BATALC Specified targetisadirectory, = 
[EROFS =———~—é«i;3B220-—— Read-only file system. 
[EUNKNOWN  —s[3474.— ss [Unknown system state. = 
[EITERBAD  =——s«(34750—— iterator isnotvalid. = 
[EITERSTE  =—sS*(3476 ~—S—SCs=|Iterator is in wrong state for operation. 
[EHRICLSBAD —s [3477 Ss HIRI classisnotvalid. 
[EHRICLBAD ~—s([3478 = {IRI subclassisnot valid. = 
[EHRITYPBAD —[3479 Ss {HRI typeisnotvalid, = 
[ENOTAPPL —=—s*[3480.—~——Ss [Datta requested is not applicable. = 
[EHRIREQTYP  =—[3481_ = {ARI request type isnot valid. 
[EHRINAMEBAD —_ [3482s {HRT resource name isnot valid. 
[EDAMAGE —s([3484.————s [A damaged object was encountered. 
[ELOOP  ———~™—=é«S;3485— SA cop exists in the symbolic links. 
[ENAMETOOLONG [3486 = {Apathnameistoolong, 
[ENOLCK = =——s«*(3487,——s No locksare available. = 
[ENOTEMPTY —*[3488 ~=——Ss[Directory isnotempty. = 
[ENOSYSRSC [3489s System resources are not available. = 
[ECONVERT =— [3490s |Conversionerror, 


[E2BIG [3491 [3491 Ss [Argumentlististoolong, [Argument lististoolong, = is too long. 
—=———— 3492 Conversion stopped due to input character 
that does not belong to the input codeset. 


[ETYPE  ——™ [3493 [3493 |Objecttypemismatche type [Object type mismatch, 
—— 3494 Attempted to reference a directory that 
was not found or was destroyed. 
EBADOBJ 3495 Attempted to reference an object that was 
not found, was destroyed, or was 
damaged. 
EIDXINVAL 3496 Data space index used as a directory is not 
valid. 
[ESOFTDAMAGE [3497 [3497 [Objecthas softdamage. [Objecthas softdamage. soft damage. 


Soe | OTENROLL 3498 User is not enrolled in system distribution 
ies sae———— 


[EOFFLINE = 3499 [3499 |Objectissuspended. is suspended. 


[34990 
oe —— [3 500 [Object i is a read-only object. 


EEAHDDSI 3501 Hard damage on extended attribute data 
space index. 

EEASDDSI 3502 Soft damage on extended attribute data 
space index. 

EEAHDDS 3503 Hard damage on extended attribute data 
space. 

EEASDDS 3504 Soft damage on extended attribute data 

| | ee 


[EEADUPRC [3505 [Duplicate extended attribute record. 


ELOCKED 3506 Area being read from or written to is 
locked. 


[EFBIG [3507 [3507 ss |Objecttoolarge. [Objecttoolarge, large. 
509 


a—_—— 3 The semaphore, shared memory, or 
message queue identifier is removed from 
the system. 

OMSG e The queue does not contain a message of 


the desired type and (msgflg logically 
ANDed with IPC_NOWAIT). 


[EFILECVT = [351k [File ID conversion of a directory failed. ID conversion of a [File ID conversion of a directory failed. failed. 

a——— _— A file ID could not be assigned when 
linking an object to a directory. 

[ESTALE [3513 [File handle was rejected by server. handle was [File handle was rejected by server. by server. 


es} — oes 
[ENOTSIGINIT ——[3516 [Process is not enabled for signals. 

[ECHILD  =———~—=«~S(;B'SS'T.— Ss Nochild process. 
[EBADH = =—sS«(3520.——sHandleisnotvalid, = 


iN YREFS 3523 The operation would have exceeded the 


maximum number of references allowed 
for a descriptor. 


[ENOTSAFE =——s [3524s |Functionisnotallowed. = 
ESC aW—— sk —— pice ee ——— 
[EIRNDAMAGE ~—[3526 Ss |Jourmalisdamaged. 
[EJRNINACTIVE ~— [3527s |Jourmalisimactive, = 
[EIRNRCVSPC [3528 = s‘|Journal space or system storage error. 
[EIRNRMT = ——s*(3529, Ss Journalisremote. 
[ENEWJRNRCV [3530s [New journal receiver isneeded. 
[ENEWJRN  ———s«(3531.=——Ss New journalisneeded. = 
[EJOURNALED [3532s Objectalready journaled. = 
[EIRNENTTOOLONG 3533 [Entry istoolargetosend. 
[EDATALINK —s [3534s [Object is adatalink object. 
[ENOTAVAIL ~—s 3535. IASPisnotavailable. = 


[ENOTTY = OTTY [35360 [I/O control operation is not appropriate. control [I/O control operation is not appropriate. is not appropriate. 

sues 3540 Attempt to write or truncate file past its 
=o ie file size limit. 

[ETXTBSY [35430 [Textfilebusy. file [Textfilebusy. 

SENG OTSET ~— [ASP group not set forthread. [ASP group not set forthread. not set for thread. 


—— a A system call was interrupted and may be 
restarted. 
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